cymulate-mcp-tools

Community MCP (Model Context Protocol) server for the Cymulate security validation platform. Exposes 100% of the Cymulate REST API (337 endpoints, OpenAPI v2.0.62) via 100 first-class semantic tools + 1 generic REST fallback + 5 utility tools = 106 total.

Covers BAS (Breach & Attack Simulation), Exposure Validation, Exposure Analytics, Attack Surface Management, Advanced Scenarios (Purple Team), Findings, Auto Remediation, Environments/Agents, and Platform administration.

Status

Unmaintained since 2026-08-07. Last tested against Cymulate API v2.0.62 (OpenAPI 3.1.1). The original author no longer uses the Cymulate platform. Issues will remain open; community PRs are welcome and will be reviewed on a best-effort basis. Fork freely.

This is a community MCP — not affiliated with, endorsed by, or supported by Cymulate Ltd. All trademarks belong to their respective owners. Verify your Cymulate Terms of Service permits third-party API clients before use.

Related MCP server: cisco-secure-access-mcp

Coverage vs official Cymulate MCP

How it works

sequenceDiagram
    autonumber
    participant U as User
    participant C as Claude/MCP Client
    participant S as cymulate-mcp
    participant V as Zod Validator
    participant X as CymulateClient
    participant A as Cymulate REST API

    U->>C: "Launch BAS assessment on endpoint module"
    C->>S: tools/call: cymulate_bas_launch { module: "endpoint", ... }
    S->>V: validate input schema
    V-->>S: parsed & type-safe args
    S->>X: POST /v1/edr/start (adds x-token header)
    X->>A: HTTPS request
    A-->>X: 200 OK + assessment_id + X-RateLimit-* headers
    X-->>S: mapped response (semantic errors on 4xx/5xx)
    S-->>C: structured result + rate-limit warning if remaining < 10
    C-->>U: renders result

When to use which tool

flowchart TD
    Start[Need to call Cymulate API] --> Q1{Common lifecycle<br/>operation?}
    Q1 -->|Yes: launch/stop/status/report| BAS[cymulate_bas_* — 7 unified tools<br/>module enum: endpoint, waf, web_gateway, ...]
    Q1 -->|Yes: EV/EA/ASM/Findings/etc.| FC[Use first-class semantic tool<br/>see CATALOG.md — 100 tools]
    Q1 -->|No — rare/new endpoint| Q2{Know the path?}
    Q2 -->|Yes| GENERIC[cymulate_api_call<br/>generic REST fallback]
    Q2 -->|No — need to discover| INSPECT[cymulate_api_list_endpoints<br/>then cymulate_api_describe_endpoint<br/>then cymulate_api_call]
    BAS --> Done[Response with rate-limit awareness]
    FC --> Done
    GENERIC --> Done
    INSPECT --> Done

Setup

Requirements

• Node.js ≥ 20

• A Cymulate account with API access enabled (generate an API key in the Cymulate console → Settings → API Keys)

Install

git clone https://github.com/lyonzin/cymulate-mcp-tools.git
cd cymulate-mcp-tools
npm install
cp .env.example .env
# Edit .env: set CYMULATE_API_KEY
npm run build

Run

# STDIO (for MCP clients like Claude Code, Cursor, Continue)
npm start

# HTTP Streamable (for remote hosting)
npm run start:http
# Listens on http://127.0.0.1:9494/mcp by default

Register with an MCP client

Claude Code (CLI)

claude mcp add cymulate node /absolute/path/to/cymulate-mcp-tools/dist/index.js

Then set the API key in the shell that spawns Claude, or edit ~/.claude.json:

{
  "mcpServers": {
    "cymulate": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/cymulate-mcp-tools/dist/index.js"],
      "env": {
        "CYMULATE_API_KEY": "your_key_here",
        "CYMULATE_API_BASE": "https://api.us-app.cymulate.com"
      }
    }
  }
}

Cursor / Continue / other MCP clients

Same JSON shape as above — most MCP clients accept a mcpServers map. Point command to node and args to the built dist/index.js.

HTTP mode (remote MCP host)

Start the server in HTTP mode:

MCP_TRANSPORT=http MCP_HTTP_PORT=9494 npm start

Then register the endpoint URL in your MCP client instead of a local command.

Environment variables

Tool catalog (18 categories, 106 tools total)

Full list with descriptions in CATALOG.md. Condensed:

Naming convention: cymulate_<domain>_<action>[_<subject>].

Architecture

• Dual transport in one binary — STDIO for local MCP clients, HTTP Streamable for remote hosting. Select via MCP_TRANSPORT.

• Zod schemas everywhere — input validated before touching the API. Type-safe.

• Rate-limit awareness — client parses X-RateLimit-Remaining on every response; tools return a warning when < 10 remaining.

• Semantic error mapping — 401/403/404/429/5xx get MCP-native error codes, not raw HTTP noise.

• OpenAPI spec cached in memory — cymulate_openapi_spec and cymulate_api_describe_endpoint serve from cache after cold start.

• Idempotency + destructive hints — every tool declares readOnlyHint / idempotentHint / destructiveHint in MCP annotations for client-side confirmation prompts.

Development

npm run dev        # tsx watch mode
npm run typecheck  # tsc --noEmit
npm run build      # tsc → dist/
npm run clean      # rimraf dist

Smoke test against real tenant

node scripts/smoke.mjs   # probes 27 endpoints, reports pass/fail by group
node scripts/mcp-probe.mjs  # boots MCP server, verifies tools/list

Contributing

Community PRs welcome. Because the project is unmaintained by the original author:

• Please include a reproducible test case (a smoke.mjs-style probe against the changed area is ideal).

• If Cymulate's API drifts (new endpoints, breaking changes), open an issue with the OpenAPI diff — a maintainer from the community can pick it up.

• Fork freely if you need faster iteration.

License

MIT — see LICENSE.

Disclaimer

This is an independent, community project. It is not affiliated with, endorsed by, or supported by Cymulate Ltd. "Cymulate" is a trademark of Cymulate Ltd. Verify your Cymulate Terms of Service permits third-party API clients before using this software.