TrafficMorph MCP Server

████████╗██████╗  █████╗ ███████╗███████╗██╗ ██████╗
╚══██╔══╝██╔══██╗██╔══██╗██╔════╝██╔════╝██║██╔════╝
   ██║   ██████╔╝███████║█████╗  █████╗  ██║██║
   ██║   ██╔══██╗██╔══██║██╔══╝  ██╔══╝  ██║██║
   ██║   ██║  ██║██║  ██║██║     ██║     ██║╚██████╗
   ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝     ╚═╝     ╚═╝ ╚═════╝
        ███╗   ███╗ ██████╗ ██████╗ ██████╗ ██╗  ██╗
        ████╗ ████║██╔═══██╗██╔══██╗██╔══██╗██║  ██║
        ██╔████╔██║██║   ██║██████╔╝██████╔╝███████║
        ██║╚██╔╝██║██║   ██║██╔══██╗██╔═══╝ ██╔══██║
        ██║ ╚═╝ ██║╚██████╔╝██║  ██║██║     ██║  ██║
        ╚═╝     ╚═╝ ╚═════╝ ╚═╝  ╚═╝╚═╝     ╚═╝  ╚═╝

Drive TrafficMorph from Claude Desktop, Claude Code, Cursor, or any other host that speaks the Model Context Protocol.

The flagship use case is CI-failure triage:

"My TrafficMorph CI step just failed on run 1234 — what regressed vs the baseline?"

→ Claude calls the right tools, fetches the relevant runs, computes the per-metric delta, and produces a human-readable triage report in seconds.

Current release: 1.2.0 — 25 tools + 4 prompts + 5 resources (34 catalog entries total). See CHANGELOG.md for the per-release history and STABILITY.md for what 1.x commits to keeping stable. See MCP-USAGE.md for worked example conversations.

Quick start

Four steps from zero to "Claude is driving my TrafficMorph account":

1. Get an API key

Open the TrafficMorph app → Settings → API Keys → click Generate. Copy the tm_… value.

2. Install (or skip — uvx runs without install)

# Permanent install:
pip install tm-mcp

# OR — no install at all. The MCP host config below uses `uvx`,
# which downloads + caches the package on first run. Confirm
# uvx itself is on your PATH:
uvx --version

Note: tm-mcp is a long-running MCP server, not a CLI with a --help flag. Invoking it directly without env vars exits 2 with a configuration error. The host (Claude Code / Desktop) subprocesses it and pipes JSON-RPC over stdio — you don't run it yourself unless you're debugging.

3. Register with your MCP host

Both Claude Code and Claude Desktop use the same env-var protocol: TM_API_KEY for the API key, TM_BASE_URL for the base URL. The server reads both at startup and fails fast with a clean "couldn't start" message if either is missing — your host's log shows that instead of opaque "tool call failed" errors later.

In all snippets below, replace two placeholders with your own values:

• TM_API_KEY=tm_xxxxxxxxxxxxxxxx → the API key from Step 1.

• TM_BASE_URL=https://YOUR-TRAFFICMORPH-HOST → the URL of your TrafficMorph server. Common values:

  • Local dev: http://localhost:8080

  • Self-hosted prod: https://trafficmorph.your-company.com (or whatever URL your install lives at)

  • Cloud SaaS: the URL shown in your TrafficMorph app's browser address bar

  • Do not copy the literal YOUR-TRAFFICMORPH-HOST placeholder — it won't resolve and every tool call will fail.

Claude Code — one command:

claude mcp add trafficmorph \
  -e TM_API_KEY=tm_xxxxxxxxxxxxxxxx \
  -e TM_BASE_URL=https://YOUR-TRAFFICMORPH-HOST \
  -- uvx tm-mcp

Project-scope alternative — drop this at the repo root:

// .mcp.json
{
  "mcpServers": {
    "trafficmorph": {
      "command": "uvx",
      "args": ["tm-mcp"],
      "env": {
        "TM_API_KEY": "tm_xxxxxxxxxxxxxxxx",
        "TM_BASE_URL": "https://YOUR-TRAFFICMORPH-HOST"
      }
    }
  }
}

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your OS, then restart Claude Desktop:

{
  "mcpServers": {
    "trafficmorph": {
      "command": "uvx",
      "args": ["tm-mcp"],
      "env": {
        "TM_API_KEY": "tm_xxxxxxxxxxxxxxxx",
        "TM_BASE_URL": "https://YOUR-TRAFFICMORPH-HOST"
      }
    }
  }
}

4. Verify

In Claude Code:

> /mcp

You should see trafficmorph listed with 25 tools, 4 prompts, and 5 resources. If you see red / error, check:

claude mcp list                # is `trafficmorph` registered?
claude mcp get trafficmorph    # what env vars + command?

The most common gotcha: forgetting TM_BASE_URL. The server refuses to start without it and surfaces a clear "$TM_BASE_URL is not set" error in your MCP host's log. Set it in the host config (see step 3).

What you can do

Conversational examples — try any of these once the server is wired up:

• "List my TrafficMorph profiles."

• "Show me the last 5 runs for profile 42."

• "Start a run on profile 42 and wait for the verdict."

• "Create a profile 'smoke-test' hitting https://api.example.com/health at 50 RPS for 60s."

• "What domains am I cleared to load-test against?"

• "Add api.example.com as a new domain and walk me through verification."

• "Compare run 1234 against run 1198."

Or invoke a slash-command prompt for a guided workflow:

• /tm_triage 42 — find the most recent failed run for profile 42, diff against the latest PASS baseline, narrate the regression.

• /tm_setup_loadtest https://api.example.com 100 60 — handle domain verification + profile creation + optional immediate run.

• /tm_compare_baseline 42 — quick regression check vs the last green.

• /tm_import_capture_guided ~/.trafficmorph/captures/my.jsonl — analyse → preview → import workflow.

Or @-mention a resource to pull pre-baked context into the chat:

• @tm://profiles — your full profile list as session-start context.

• @tm://history/recent — the last 20 runs across all profiles.

• @tm://domains — verified domain list.

• @tm://profiles/42 or @tm://history/1234 — one specific entity by id.

See MCP-USAGE.md for end-to-end worked conversations including failure triage, new-test setup, and capture-driven profile import.

Full catalog

Tools (25) — AI-invoked actions

Prompts (4) — user-invoked slash commands

Prompts return a templated user message that steers the AI through a specific tool sequence. They're how you kick off a known workflow without typing the full natural-language description every time.

Resources (5) — @-mention URIs

Resources are read-only data the host pulls into context — usually at session start via @-mention. They wrap the corresponding read tools 1:1; the difference is who decides when to read (AI for tools, host for resources).

Configuration

Capture-file path validation

tm_analyse_capture and tm_import_capture accept a server-side file path. The MCP server validates each path before passing it through:

Override the root via TM_MCP_CAPTURE_ROOT in your MCP host's server config:

"env": {
  "TM_API_KEY": "...",
  "TM_BASE_URL": "...",
  "TM_MCP_CAPTURE_ROOT": "/path/to/your/captures"
}

Troubleshooting

Server fails to start with $TM_API_KEY is not set or $TM_BASE_URL is not set. One of the required env vars wasn't delivered to the subprocess by your MCP host. The error names the missing variable; add it to the env block in your host config (see Step 3).

Server starts, but every tool call hits a network / DNS error. TM_BASE_URL is set to something that doesn't resolve — typically a placeholder like https://YOUR-TRAFFICMORPH-HOST that wasn't edited, a typo in the hostname, or an internal URL not reachable from where the MCP host runs. Read the URL back from claude mcp get trafficmorph and confirm it resolves with curl -I "$TM_BASE_URL/api/v1/profiles".

Tools work, but specific ones return 404. Your TrafficMorph server is running an older build that doesn't expose those endpoints yet. Upgrade the server.

PLAN_UPGRADE_REQUIRED on every call. Your TrafficMorph account doesn't have API access enabled. Check your account settings, or point the MCP server at a deployment where your account has API access.

tm_create_profile refuses with "A profile named X already exists". The server's POST endpoint is upsert-by-name and would silently replace the existing profile (including scripts / callbacks / alerts the MCP tool surface doesn't expose). Use tm_update_profile(profile_id=<id from error>) instead, or pick a unique name.

tm_update_profile refuses to rename. A rename would collide with another profile under your account. The error names both ids; either pick a unique new name OR call tm_update_profile against the OTHER profile if you actually meant to edit that one.

Domain verify returns 400 immediately. That's the fail-fast contract — verification is NOT polling-style. The 400 message includes the expected TXT record / URL + token; read it back to the user, wait for them to install the record / file, then retry.

Versioning

The MCP server is a thin layer over the trafficmorph Python SDK. The dependency pin in pyproject.toml constrains the SDK range this release is tested against; updating the SDK ships as a new tm-mcp release.

See also

• MCP-USAGE.md — comprehensive user guide with worked example conversations

• CHANGELOG.md — per-release history

• STABILITY.md — v1.0 stability promise (what tools / prompts / resources stay stable across 1.x)

• examples/ — full conversation transcripts (triage, setup, capture import)

• TrafficMorph Python SDK — the HTTP layer this MCP server uses