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.

---

Coverage vs official Cymulate MCP

	This project	Official Cymulate MCP
Endpoints covered	337 / 337 (100%)	~130 / 337 (39%)
First-class tools	100	118
Generic REST fallback	✅ cymulate_api_call	❌
BAS full coverage (all 11 modules)	✅	Partial
Auto Remediation	✅	❌
ASM	✅	❌
Advanced Scenarios (Purple Team)	✅	Partial
HTTP Streamable transport	✅	STDIO only
Rate-limit awareness in responses	✅	❌
OpenAPI self-inspection tools	✅	❌

---

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

Variable	Default	Required	Purpose
CYMULATE_API_KEY	—	✅	API key from Cymulate console
CYMULATE_API_BASE	https://api.us-app.cymulate.com		REST API base URL (change for EU tenant: https://api.app.cymulate.com)
MCP_TRANSPORT	stdio		stdio or http
MCP_HTTP_HOST	127.0.0.1		HTTP bind host (only in http mode)
MCP_HTTP_PORT	9494		HTTP bind port
CYMULATE_REQUEST_TIMEOUT_MS	60000		Per-request timeout
CYMULATE_MAX_RETRIES	2		Retries on 429/5xx
MCP_LOG_LEVEL	info		debug, info, warn, error

---

Tool catalog (18 categories, 106 tools total)

Full list with descriptions in CATALOG.md. Condensed:

#	Category	Tools	Purpose
1	BAS Attack Simulation (unified)	7	Launch/stop/status/report across 11 BAS modules via module enum
2	Immediate Threats	5	Threat catalog, IOCs, MITRE mapping, SIEM detection
3	Full Kill-Chain (FKC)	4	FKC scenarios + campaigns, agent selection
4	Attack Surface Management (ASM)	5	Scan trigger, history, findings
5	Advanced Scenarios (Purple Team)	6	Template CRUD, actions catalog
6	EV — Launched Assessments	6	List, create, get, delete, filters
7	EV — Scheduled Assessments	6	Schedule CRUD + configurations
8	EV — Templates + Smart Templates	8	Template CRUD + smart templates
9	EV — Scenarios	5	Scenario CRUD
10	EV — Threats	5	Threat listing + auto-run schedules
11	EV — Resources	4	Resource CRUD + filters
12	EV — Input Configs + Groups + Pre-Reqs + WAF	9	Assessment prerequisites, template grouping
13	Exposure Analytics (EA)	8	CVEs, exposures, remediation tasks + export
14	Findings + Auto Remediation	6	Findings search + auto-remediation apply
15	Environments + Agents	8	Env CRUD, agent listing (connected/all), hashes
16	Platform (SSO/Score/MITRE/Trace/Activity)	5	Admin dashboards, MITRE ATT&CK coverage
17	General Info	3	Activity center, users, integrations
18	Utility & Fallback	6	cymulate_api_call, endpoint discovery, health, OpenAPI, debug

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.