Skip to main content
Glama

TrafficMorph MCP Server

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

PyPI Python versions License

Drive TrafficMorph from Claude Code, Claude Desktop, Codex, 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.

Catalog: 37 tools + 4 prompts + 5 resources (46 entries). 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

Every supported host uses 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:8092

    • 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"
      }
    }
  }
}

Codex — add to ~/.codex/config.toml (the Codex CLI reads MCP servers from this file at startup), then restart Codex. Note the TOML shape: a [mcp_servers.<name>] table with command / args and an inline env table.

[mcp_servers.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 37 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).

Related MCP server: jmeter-mcp

Security

You've just put a long-lived API key — full access to your TrafficMorph account — into a config file on disk. A few real gotchas worth knowing about:

Don't commit / share / paste the host config file

The token sits in plaintext in your MCP host's config:

  • Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) / %AppData%\Claude\claude_desktop_config.json (Windows)

  • Claude Code — managed via claude mcp add, stored in ~/.claude/

  • Codex — ~/.codex/config.toml

  • Cursor — ~/.cursor/mcp.json

If you sync dotfiles to a public repo, paste your config into a support ticket, or DM it to a colleague to help them set up tm-mcp, you've leaked the token. Treat the file like an SSH private key. If it does leak, rotate immediately in the TrafficMorph app (Settings → API Keys → Regenerate) — the old key is revoked the moment the new one is generated.

Use env vars in the host config, never CLI args

tm-mcp hard-rejects any command-line argument other than --help / -h. This is deliberate — credentials passed via argv would show up in ps -ef, system audit logs, crash dumps, and any monitoring agent that records process command lines.

Right (what the Quick start above shows):

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

Wrong (will refuse to start with command-line arguments are not supported):

"trafficmorph": {
  "command": "uvx",
  "args": ["tm-mcp", "--api-key=tm_xxxxxxxxxxxxxxxx"]
}

Verbose MCP-host logging can capture credentials

Most MCP hosts have a debug / verbose mode that logs every subprocess startup including its env block. If you enable that to troubleshoot something else, your TM_API_KEY will appear in the host's log file. Disable verbose logging once you're done debugging, and consider rotating the key if the log file ever left your machine.

Trust boundary is the MCP host itself

Any MCP host you configure tm-mcp into has full read access to the env vars you pass it (that's what makes it work). Only configure tm-mcp in hosts you trust — same posture as installing any local CLI tool or IDE extension.

Server-side defences (already in place)

  • Network leg uses HTTPS to your TrafficMorph deployment (the underlying trafficmorph SDK validates the base URL on startup and refuses non-http/https schemes).

  • Tokens are hashed at rest server-side, never stored in plaintext in the database.

  • Every tm_… token is revocable independently — rotating one key doesn't affect the rest of your account.

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 (37) — AI-invoked actions

Tool

Action

Read

tm_list_profiles

List all profiles owned by the authenticated user

tm_get_profile

Full config + run status for one profile

tm_list_history

Paginated past runs with filters (auto_verdict=FAIL is the CI-triage filter)

tm_get_run

Full metric set + verdict for one run (include_series=False drops the per-bucket series)

tm_list_domains

All registered domains + verification status

tm_compare_runs

Metric-by-metric diff of two runs plus the server's significance tests

tm_get_run_status

Live progress of a profile's current run (RPS, response codes, last minute of latency)

tm_list_regions

Dispatch regions available to the account

tm_get_account

Plan, limits (RPS, concurrent runs, profiles, quotas) and this month's usage

tm_list_history_filters

Profiles, regions, tags and verdicts the history filters accept

tm_export_profile

Portable trafficmorph-profile-v1 document (same as the web UI's Export)

tm_analyse_capture

Per-endpoint analysis of a JSONL capture file

tm_list_capture_sources

Remote capture sources (SFTP / S3) configured in the web UI; no credentials

tm_list_capture_source_files

Capture files in one remote source, newest first

tm_analyse_remote_capture

Per-endpoint analysis of a capture file in a remote source

Run control

tm_start_run

Start a run, optionally in a given region and with history tags; with wait=True + fail_on_verdict=["FAIL","WARN"] mirrors tm runs start --wait in the CLI

tm_stop_run

Stop the in-flight run for a profile (idempotent)

tm_pause_run

Pause without losing position (idempotent)

tm_resume_run

Resume a paused run from where it left off

Profile lifecycle + capture import

tm_create_profile

Create a new profile, optionally with scripts, callback URL, alert policy, weekly schedule, variables sets, default region, readiness URL and interpolation mode (fails fast on name collision to prevent silent upsert wipe)

tm_update_profile

Partial update by id (read-modify-write internally — only pass the fields you want to change)

tm_delete_profile

Remove a profile

tm_import_capture

Persist analysed-capture groups as profiles

tm_import_remote_capture

Same, for a capture file in a remote source

tm_import_profile

Create a profile from a portable document; refuses to overwrite unless overwrite=True

tm_delete_schedule

Remove a profile's schedule (idempotent)

tm_delete_run

Delete one run from history

Domain management

tm_add_domain

Register a domain for verification (idempotent)

tm_verify_domain_dns

Check the TXT challenge record

tm_verify_domain_http

Check the /.well-known/trafficmorph-verify.txt file

tm_delete_domain

Remove a domain

Variables-set lifecycle

tm_list_variables_sets

List all variables sets owned by the user

tm_get_variables_set

Single set's metadata (id, name, mode, columns, row count)

tm_create_variables_set

Upload a CSV-style set (inline csv_content string, mode is one of "ROW" / "COLUMN" / "SEQUENTIAL")

tm_rename_variables_set

Rename without touching content (idempotent)

tm_change_variables_set_mode

Switch between ROW / COLUMN / SEQUENTIAL without re-uploading

tm_delete_variables_set

Remove a set; 400s if still attached to any profile (detach via tm_update_profile(variables_set_ids=...) first)

Read tools carry readOnlyHint=true, so hosts can run them without a confirmation prompt. Run-history payloads come back with their metric maps (latencyQuantiles, responseCodes, series, verdict reasons) decoded into JSON objects.

Server compatibility. tm_get_run_status, tm_list_regions, tm_start_run(region=/tags=), the significance part of tm_compare_runs, the variables-set / region / readiness / interpolation profile fields, and the account, history-filter, schedule-delete, run-delete, export / import and remote-capture tools need a TrafficMorph server that has them in /api/v1. Against an older server those calls fail (compare falls back to its client-side diff), and tm_update_profile still resets those four profile settings.

Known limitations:

  • tm_start_run(wait=True) no longer blocks other calls and sends progress notifications, but the MCP host's own tool-call timeout still applies; for runs longer than that, use wait=False and poll tm_get_run_status.

Prompts (4) — user-invoked slash commands

Slash command

Workflow

/tm_triage <profile_id>

Find the most recent FAIL → diff vs latest PASS → narrate the regression

/tm_setup_loadtest <url> <rps> <duration_seconds>

Domain verification (if needed) + profile creation + optional run

/tm_compare_baseline <profile_id>

Quick regression check: latest run vs latest PASS

/tm_import_capture_guided <path>

Analyse → present groups → user picks → import

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

URI

What it returns

tm://profiles

All your profiles, JSON

tm://profiles/{id}

One profile's full config

tm://history/recent

Last 20 runs across all profiles

tm://history/{run_id}

One run's full metrics

tm://domains

All registered domains + verification status

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

Env var

Required

Notes

TM_API_KEY

yes

Full tm_… value provisioned from in-app Settings → API keys

TM_BASE_URL

yes

URL of your TrafficMorph install (http://localhost:8092 for local dev, your hosted URL otherwise). No built-in default — the server refuses to start without it

TM_MCP_CAPTURE_ROOT

no

Defaults to ~/.trafficmorph/captures/. Allow-listed root for tm_analyse_capture + tm_import_capture file paths

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:

Rule

Why

Must resolve inside $TM_MCP_CAPTURE_ROOT (default ~/.trafficmorph/captures/)

Prevents AI invocation from probing ~/.ssh/, ~/.aws/, ~/Documents/…

Symlinks resolving outside the root are rejected

Classic symlink-escape defense

.. segments rejected at parse time

Path-traversal defense

Only .jsonl extension

The capture parser reads plain JSONL (no gzip wrapping)

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 every field of the existing profile, including settings you didn't pass. 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.

"Could not reach the TrafficMorph server at …". No HTTP response came back: the server isn't running, or TM_BASE_URL in the MCP host config points at the wrong place. The error names the URL it tried.

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

Source

Notes

MCP server release

tm-mcp on PyPI

Pin via pip install 'tm-mcp==X.Y.Z'. See CHANGELOG.md.

API version

tm_mcp.__version__ matches the PyPI version

Use to identify what's installed in support tickets

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

Available Tools

25 tools
tm_add_domainA
DestructiveIdempotent

Register a new domain for verification. Returns the VerifiedDomainResponse record carrying a single verificationToken plus pre-formatted setup instructions for both verification methods.

Verification is required before TrafficMorph will run traffic against the domain — it's the gate that prevents arbitrary abuse-as-a-service. Two verification methods are offered; the same token is used for both — pick whichever method is easier to set up:

  • DNS — install the token as a TXT record at _trafficmorph-verify.<domain>. Best for users who control DNS. Use :func:tm_verify_domain_dns after the record propagates.

  • HTTP — serve the token at https://<domain>/.well-known/trafficmorph-verify.txt. Best when DNS access is restricted. Use :func:tm_verify_domain_http once the file is live.

Response shape::

{
    "id": 7,
    "domain": "api.example.com",
    "verificationToken": "tm-verify-abc123…",
    "verificationMethod": null,           # set after verification
    "verified": false,
    "verifiedAt": null,
    "createdAt": "2026-05-16T12:00:00Z",
    "dnsInstruction": "Add a TXT record for _trafficmorph-verify.api.example.com with value: tm-verify-abc123…",
    "httpInstruction": "Place a file at https://api.example.com/.well-known/trafficmorph-verify.txt containing: tm-verify-abc123…"
}

The dnsInstruction / httpInstruction strings are pre-formatted by the server for verbatim display — the AI host can read either back to the user without composing the setup steps itself.

Idempotent: calling again with the same domain returns the existing record with the same token (the server treats repeat registrations as no-ops).

Inputs: domain (required).

tm_analyse_captureA

Analyse a JSONL traffic capture and return the proposed profile structure.

capture_path must point to a .jsonl file under $TM_MCP_CAPTURE_ROOT (defaults to ~/.trafficmorph/captures/). .jsonl.gz and other compressed forms are NOT supported — the server-side parser reads plain text only. Symlinks resolving outside the root, path-traversal sequences, and other extensions are rejected by the path validator in :mod:tm_mcp.capture_path — see its module docstring for the security rationale.

Returns per-endpoint analysis: URL skeleton with $$macro$$ placeholders, derived RPS curve, extracted variables, sample URLs. No state is persisted. Pair with :func:tm_import_capture to actually create profiles from the analysis.

Inputs: capture_path (required).

tm_change_variables_set_modeA
DestructiveIdempotent

Switch sampling mode on an existing set without re-uploading the CSV. Accepts any of the three modes: ROW, COLUMN, SEQUENTIAL.

Common use cases:

  • A capture-import-created set lands in ROW mode by default; flip to SEQUENTIAL for ordered replay that reproduces the original traffic order.

  • A set originally created with ROW (correlated per-row sampling) can be flipped to COLUMN if you want uncorrelated combinations across columns instead.

The server re-parses the stored CSV with the target mode and 400s if the CSV is incompatible — e.g. switching to ROW when the CSV has no weight column. The error message names the actual cause so the AI host can either:

  • Fix the underlying CSV (delete + re-upload with the right shape).

  • Stay in the current mode.

Returns the updated metadata.

Inputs: variables_set_id (required), mode (required).

tm_compare_runsA

Synthetic side-by-side diff of two runs.

No equivalent /api/v1 endpoint exists — this tool fetches both runs and computes the delta client-side. Note: the response shape here is the MCP server's own — distinct from the native RunComparisonService's RunComparisonResponse. The MCP shape is leaner (no full run summaries embedded) because the AI rarely needs every field, and a separate tm_get_run call surfaces the full per-run detail if needed.

Return shape:

.. code-block:: python

{
    "run_id": <int>,                    # the newer run's id (post-swap)
    "baseline_run_id": <int>,           # the older run's id (post-swap)
    "verdict_change": {
        "run": <str|None>,              # e.g. "FAIL"
        "baseline": <str|None>,         # e.g. "PASS"
    },
    "deltas": {
        "<metric_name>": {
            "a": <number>,              # value from `run`
            "b": <number>,              # value from `baseline`
            "delta_pct": <float|None>,  # None when baseline is 0
            "delta_abs": <number>,      # only when delta_pct is None
            "regression": True,         # only when above +10% in a "bad" direction
        },
        ...
    },
}

Metrics covered: totalRequests, totalErrors, avgRps, peakRps, successRate, durationSeconds (top-level), plus latency_<quantile> rows for every quantile present in both runs (latency_p50, latency_p95, etc.).

Regression flag fires only for metrics with a known "bad direction": totalErrors UP, successRate DOWN, any latency quantile UP. Throughput / duration deltas are reported without regression flags — the AI host interprets direction based on context.

Threshold is intentionally generous (10%) — the server's auto-comparison uses tighter thresholds for the official verdict; this tool is a "draw attention to these metrics" surface for the AI to narrate alongside the verdict.

Invariants enforced — mirror the native RunComparisonService.compare(...) server method (RunComparisonService.java line ~61):

  1. run_id != baseline_run_id (comparing a run to itself produces a useless all-zero diff that would mislead the AI).

  2. Both runs belong to the same profile (cross-profile compares mix incomparable workloads — e.g. checkout-flow vs login-flow latency — and produce % deltas that look valid but answer no real question).

  3. Most-recent run is returned as run when createdAt is present and parseable on both runs. The tool compares parsed datetimes (UTC-aware, normalized from naive input) and swaps the caller's arguments if it detects "older first" — the result narrative then reads "newer run regressed vs older baseline" consistently. Order detection uses parsed-datetime comparison, not raw string compare, so ISO-8601 fractional-seconds and offset variants behave correctly.

    Fallback: when either run is missing createdAt or the value can't be parsed, the tool keeps the caller- supplied order rather than guessing. That's an intentional safety net — better to surface the diff in the order the AI asked for than to silently rearrange based on weak signals — but it means the "newer = run" invariant only holds when timestamps are usable. Mirrors the native service's own defensive null-handling.

Inputs: run_id (required), baseline_run_id (required).

tm_create_profileA
Destructive

Create a new traffic profile (upsert by name — see below).

Minimum viable profile = name + target_url + duration_seconds + points. The points array is the RPS curve as a list of {"x": seconds, "y": rps} dicts — e.g. [{"x": 0, "y": 10}, {"x": 60, "y": 100}] ramps from 10 to 100 RPS over the first minute.

Optional shape knobs:

  • http_method — defaults server-side to POST if omitted.

  • request_body — string body sent on every request.

  • request_headers — JSON-encoded header list, e.g. '[{"name":"Authorization","value":"Bearer ..."}]'. Must be a string (the API accepts a string for round-tripping via the UI's form layer).

  • loop — repeat the curve indefinitely while the run is active. Defaults to False.

Not yet exposed via MCP: init / response / cleanup scripts, alert policy, callback URL, schedule. Use the web UI or the public REST API directly for those.

Name-collision behavior: the server's create endpoint is upsert-by-name, which would silently REPLACE every field of an existing profile from the request body — including advanced fields (scripts, callback, alerts) this tool doesn't expose. To prevent that data loss, this tool fails fast on collision: if a profile with this name already exists, you get a typed :class:ToolError naming the existing profile's id, and no write is attempted.

Name comparison matches the server's normalization: whitespace is trimmed and the match is per-character case-insensitive (mirrors the JDBC LOWER() lookup used by Spring Data's IgnoreCase derived query). " Existing ", "EXISTING", and "existing" all collide with an existing "Existing" profile.

ASCII names recommended. Non-ASCII names (e.g. "Straße", "İstanbul") work, but the case-fold semantics on the JVM and PostgreSQL may differ subtly from a Python-side re-implementation. The MCP guard uses str.lower() to match the server's per-character behavior (e.g. "Straße" and "STRASSE" are treated as DISTINCT names by both sides), not the more aggressive Python casefold(). For names with locale-sensitive characters, ASCII spellings give predictable cross-database behavior.

To modify an existing profile, use :func:tm_update_profile (which preserves advanced fields on partial updates). To create a fresh profile, pick a name that doesn't collide.

Concurrency caveat: the collision check is a client-side preflight against GET /profiles immediately before the POST. A concurrent POST from another session for the same user can land in the gap. For single-user MCP usage the race is sub-millisecond; for higher-concurrency scenarios the structural fix is a server-side create-if-absent contract (tracked separately).

Returns the full saved profile dict (id, name, duration, …).

Inputs: name (required), target_url (required), duration_seconds (required), points (required), +4 more.

tm_create_variables_setA
Destructive

Create a new variables set from inline CSV content.

csv_content is the full CSV as a string — header row plus data rows. The server parses + validates at upload time and rejects malformed or oversized inputs with a typed :class:ToolError.

The header row's column names define which $$macro$$ placeholders this set substitutes when attached to a profile. Example::

userId,token,weight
u-1001,tk-abc,5
u-1002,tk-def,1

Attached to a profile whose URL is https://api.example.com/users/$$userId$$ and which sends header Authorization: Bearer $$token$$, each request:

  • Picks a row (weighted random in ROW mode — row 1 with 5/6 probability, row 2 with 1/6; sequential in SEQUENTIAL mode).

  • Substitutes the row's userId and token columns into the matching placeholders.

  • Sends the resulting request.

mode defaults to "ROW" (weighted per-row sampling). Other accepted values: "COLUMN" (per-column independent sampling) and "SEQUENTIAL" (ordered walk, for captured- traffic replay). ROW mode REQUIRES a weight column (case-insensitive header); COLUMN accepts an optional shared weight column AND per-column {col}_weight overrides; SEQUENTIAL ignores weights. See the helper docstring in _validate_variables_set_mode for the full mode contract.

Returns the created set's metadata (id, name, mode, macroColumns, weightColumn, rowCount, byteSize). The AI host typically follows with attaching the new set to a profile — that's handled via tm_update_profile on the profile side (variables-set attachment is on the profile, not the set).

Quota: each account has a per-user variables-set quota. A 400 with Variables-set quota reached means delete an existing set first.

Duplicate names rejected (strict-uniqueness semantics). Per-user, names must be unique — a second create call with a name that already exists 400s with A variables set named 'X' already exists. The endpoint deliberately doesn't auto-suffix (unlike the capture-import path which does (2), (3), …). Pick a fresh name, or :func:tm_rename_variables_set / :func:tm_delete_variables_set the existing one before re-creating.

Inputs: name (required), csv_content (required), mode.

tm_delete_domainA
Destructive

Remove a registered domain.

Profiles targeting this domain remain saved but won't be runnable until another verified domain covers the target host (see :func:tm_list_domains to find what's covered).

Returns {"domain_id": <id>, "deleted": True} on success. A 400 / "Domain not found" surfaces as a typed :class:ToolError — caller can react to it without parsing message text.

Inputs: domain_id (required).

tm_delete_profileA
Destructive

Delete a profile by id. Any in-flight run is cancelled server-side; run history rows are retained (only the profile definition is removed).

Returns {"profile_id": <id>, "deleted": True} on success. A 400 / "Profile not found" surfaces as a typed ToolError — caller can react to it without parsing message text.

Inputs: profile_id (required).

tm_delete_variables_setA
Destructive

Delete a variables set. Fails fast (HTTP 400) if the set is still attached to any profile — the server does NOT auto-detach.

The server-side error message names the referencing profile(s) so the caller can detach them first. The MCP layer preserves that message verbatim in the typed ToolError so the AI host can read it back to the user. Example error text::

Can't delete 'users-fixture' — still attached to profiles:
loadtest-api.example.com, smoke-test. Detach it from those
profiles first.

To delete an attached set, the typical recovery is to call :func:tm_update_profile on each referencing profile with an updated variables-set attachment list that omits this set's id, then retry the delete. (The variables-set attachment is a property of the profile, not of the set — managed via the profile's update path, not via a separate endpoint here.)

Returns {"variables_set_id": <id>, "deleted": True} on success. A 400 / "Variables set not found" or "still attached" surfaces as a typed :class:ToolError — caller can react without parsing message text beyond the error string itself.

Inputs: variables_set_id (required).

tm_get_profileA

Get the full configuration of a single traffic profile by id.

Returns: name, RPS curve points, target URL, HTTP method, request body / headers, optional init/cleanup/response scripts, callback config, auto-alert settings, schedule (if any), AND the current run status (IDLE / RUNNING / PAUSED / COMPLETED).

400 if the profile isn't found or doesn't belong to this user (per the v1 API contract — IllegalArgumentException → 400).

Inputs: profile_id (required).

tm_get_runA

Get one run's full detail — the CI post-run inspection endpoint.

Returns the complete metric set: response-code distribution, latency quantiles (p50/p95/p99/...), RPS / latency time series, secondary stats from response scripts, the auto-comparison snapshot against the configured baseline, AND the auto-verdict

  • reasoning (autoVerdict, autoVerdictReasons).

For comparing two runs side-by-side, use tm_compare_runs — it does the metric-by-metric diff so the AI doesn't have to.

Inputs: run_id (required).

tm_get_variables_setA

Get a single variables set's metadata.

Returns the same shape as one element of :func:tm_list_variables_sets: id, name, mode, macroColumns, weightColumn, rowCount, byteSize, createdAt, updatedAt. Raw CSV omitted; use the in-app UI if you need row-level inspection.

Inputs: variables_set_id (required).

tm_import_captureA
Destructive

Import the chosen groups from an analysed JSONL capture as real traffic profiles.

Workflow: call :func:tm_analyse_capture first to inspect the derived groups (method + URL skeleton + variables + RPS curve); pick the ones you want to persist; pass them here as selections.

capture_path must be the SAME JSONL file you analysed — server re-derives the analysis on commit (the preview response deliberately doesn't carry full per-row values, so trusting client-supplied preview data would be both heavy and tamper- able). The path resolves under $TM_MCP_CAPTURE_ROOT with the same security checks as tm_analyse_capture.

selections is a dict of shape::

{
    "groups": [
        {
            "method": "POST",
            "urlSkeleton": "https://api.example.com/api/x",
            "profileName": "load-test users"  # optional
        },
        ...
    ]
}

Each (method, urlSkeleton) pair must match a group returned by the prior tm_analyse_capture call exactly — index-based references would be fragile across re-analysis (groups sort by row count, ties break alphabetically). profileName is optional; omit / null lets the server pick a default like "[capture] POST /api/x". Empty groups list is allowed (no-op; result reports zero profiles created).

Returns the server's import result: createdProfiles (array of {profileId, name}), createdVariablesSetCount, skippedSelections (with reasons), warnings.

Inputs: capture_path (required), selections (required).

tm_list_domainsA

List all domains registered by the authenticated user with their verification status.

Each entry carries id, domain, verified flag, and the DNS / HTTP challenge tokens that are still in play. Useful for answering "what domains am I allowed to load-test?" and for walking a user through verification.

Inputs: no named parameters. Returns: result

tm_list_historyA

List past runs with optional filters. The killer use case for CI-failure triage:

tm_list_history(auto_verdict="FAIL", size=10)

returns the 10 most recent failing runs across all profiles.

Filters are AND-combined:

  • profile_id: narrow to one profile.

  • triggered_by: api / ui / scheduled.

  • region: region code (e.g. us-east-1).

  • auto_verdict: PASS / WARN / FAIL / NO_BASELINE.

  • tag: arbitrary user tag.

  • from_ / to: ISO-8601 timestamps bounding startedAt. from_ is named with a trailing underscore because from is a Python keyword.

  • page / size: zero-based pagination, size capped at 100 by the server.

Returns the standard pagination envelope: {content: [...summaries...], page, size, totalElements, totalPages}.

Inputs: profile_id, triggered_by, region, auto_verdict, +5 more.

tm_list_profilesA

List all traffic profiles owned by the authenticated user.

Returns a list of lightweight summaries — one per profile — with id, name, and createdAt. Use tm_get_profile(id) for the full configuration of any single profile.

Ordering: server-default (typically most-recently-updated first). The endpoint doesn't expose a sort parameter.

Inputs: no named parameters. Returns: result

tm_list_variables_setsA

List all variables sets owned by the authenticated user.

Returns metadata only — id, name, mode, macro columns, optional weight column, row count, byte size, timestamps. The raw CSV content is NOT included (it's downloaded via a separate UI-only endpoint when needed). For a single set's full metadata use :func:tm_get_variables_set.

Useful for answering "what variables sets do I have available to attach to a profile?" — common follow-up when the AI is asked to set up a parameterized load test.

Inputs: no named parameters. Returns: result

tm_pause_runA
DestructiveIdempotent

Pause the in-flight run for a profile. Idempotent — when no run is active, returns status="IDLE" rather than erroring. Useful when a workflow wants to inspect intermediate metrics without losing progress.

Inputs: profile_id (required).

tm_rename_variables_setA
DestructiveIdempotent

Rename a variables set. Changes only the display name; the CSV content, sampling mode, and attached-profile relationships are untouched.

Returns the updated metadata (same shape as :func:tm_get_variables_set).

Inputs: variables_set_id (required), name (required).

tm_resume_runA
Destructive

Resume a paused run. Continues from the pre-pause position on the RPS curve and any SEQUENTIAL variables-set cursors. Not idempotent in the no-state case — unlike stop/pause, calling resume without an in-flight or paused run is a 400.

Inputs: profile_id (required).

tm_start_runA
Destructive

Start a traffic run for the given profile.

Default behavior (wait=False) is fire-and-return: POST to /api/v1/profiles/{id}/start, return the run id + initial status, exit. Useful for "kick this off and tell me when it's done" UI flows.

Set wait=True to drive the CI-gate shape (mirrors the tm runs start --wait CLI flow):

  1. Snapshot the profile's current top history id (so we can later distinguish "my run's row landed" from "a previous run's row is still there").

  2. Start the run.

  3. Poll /api/v1/profiles/{id} every poll_interval_seconds until status leaves {"RUNNING", "PAUSED"}.

  4. Fetch the post-run history row with bounded exponential backoff up to verdict_timeout_seconds — closes three race windows (terminal-status vs row-insert vs verdict worker; see _fetch_post_run_history for the full rationale).

fail_on_verdict triggers the gate evaluation. Accepts a list of verdict tokens — any of "FAIL", "WARN", "NO_BASELINE". PASS is deliberately not accepted. Requires wait=True (the gate needs the verdict, which requires waiting). Unknown tokens raise ToolError before any HTTP call — a typo like ["FAILL"] would otherwise produce a silent false-pass.

Return shape:

.. code-block:: python

# Without wait:
{
    "run_id": <str>,          # in-memory run id
    "profile_id": <int>,
    "status": <str>,          # initial — typically "RUNNING"
    "waited": False,
}

# With wait:
{
    "run_id": <int>,            # history row id (persisted; use with tm_get_run)
    "started_run_id": <str>,    # in-memory runId from /start (informational)
    "profile_id": <int>,
    "status": <str>,            # terminal — e.g. "COMPLETED" or "IDLE"
    "verdict": <str|None>,      # e.g. "FAIL", "PASS", "NO_BASELINE"
    "verdict_reasons": <str|None>,
    "fail_on_match": <bool|None>,  # True when verdict ∈ fail_on_verdict, OR
                                   # when gate is set but verdict is None
                                   # (fail-closed). None when fail_on_verdict
                                   # was not provided.
    "metrics": {
        "totalRequests": <int>,
        "totalErrors": <int>,
        "avgRps": <float>,
        "peakRps": <float>,
        "successRate": <float>,
        "latencyQuantiles": {<quantile>: <ms>, ...},
    },
    "verdict_pending": <bool>,  # True iff row appeared but verdict never
                                # populated within verdict_timeout_seconds
    "waited": True,
}

Run-correlation defense. Exact runId match. The server persists the in-memory runId on every RunHistory row (see RunHistory.runId field). The wait flow compares the row's runId to the one returned by /start; mismatch → fail closed with ToolError. This is the definitive correlation — no time-drift ambiguity, no race window where two starts within seconds of each other false-negative.

Additional defenses kept as belt-and-suspenders:

  • triggered_by filter on history fetches: both the pre-start snapshot and the post-run fetch filter triggered_by="api". Narrows the candidate set to rows we could plausibly have produced; protects the anchor logic from cross-channel collisions.

  • Time-drift fallback (transitional): if a row's runId is null (legacy data persisted before the column was added), falls back to the 30s forward / 5s backward drift check. Removable once production rows all carry the field.

Fail closed when ambiguous. Row with neither a runId nor a parseable startedAt → ToolError. Better to surface "can't verify identity" than silently return a possibly-wrong verdict.

Inputs: profile_id (required), wait, fail_on_verdict, wait_timeout_seconds, +2 more.

tm_stop_runA
DestructiveIdempotent

Stop the in-flight run for a profile. Fully idempotent — succeeds with status="IDLE" even when nothing is running. Any in-flight dispatch loops cancel within a tick on the server side.

Inputs: profile_id (required).

tm_update_profileA
DestructiveIdempotent

Update an existing profile by id. Fields you omit are kept as-is.

The underlying API endpoint is a full PUT (the request body replaces every field of the profile), but exposing that directly would force the AI to GET-then-PUT in two calls for every tweak. This tool does the read-merge-write internally: fetches the current profile, overlays the kwargs you provided, PUTs the merged body back.

Use this when you know the profile's id. Examples:

  • "Make this profile last 5 minutes instead of 1" → call with profile_id=42, duration_seconds=300.

  • "Switch the target to staging" → profile_id=42, target_url='https://staging.example.com/api'.

  • "Replace the RPS curve" → profile_id=42, points=[...].

Fields not yet exposed (scripts / alerts / schedule) are preserved verbatim from the existing profile.

Rename caveat: the server's PUT endpoint correctly routes by path id (it pins the request body's profile id to the path id, so the save path takes its id-based update branch). But the server does NOT enforce name uniqueness, so a rename to another profile's name would create a duplicate- named pair. To keep the data model clean and AI workflows predictable, this tool still pre-flights a GET /profiles whenever the name kwarg changes the current value, and raises :class:ToolError if the new name collides with any other profile (whitespace + case-insensitive match, mirroring the server's normalization). Updates that don't change the name skip this check entirely (no extra roundtrip).

Returns the full updated profile dict.

Inputs: profile_id (required), name, target_url, duration_seconds, +5 more.

tm_verify_domain_dnsA
DestructiveIdempotent

Run the DNS-TXT verification check on a previously-added domain.

The server looks up the TXT record at _trafficmorph-verify.<domain> and matches it against the verificationToken issued by :func:tm_add_domain. On match, the domain flips to verified=true and becomes usable as a profile target.

On miss the server returns 400 (rather than a polling- style 200 "still pending"). That's deliberate — CI flows fail fast on misconfigured DNS instead of looping forever. The 400 error message includes the expected TXT name + token, so the AI host can read it back to the user verbatim for them to copy into their DNS provider.

Success response is the same VerifiedDomainResponse shape as :func:tm_add_domain, now with verified=true, verifiedAt populated, and verificationMethod="DNS" (the server's stored value — uppercase per DomainVerificationService.markVerified L112/L148/L183; other documented values are "HTTP" and "ADMIN"). Pair with :func:tm_list_domains after a successful call to confirm the flag flipped.

Inputs: domain_id (required).

tm_verify_domain_httpA
DestructiveIdempotent

Run the HTTP-token verification check on a previously-added domain.

The server fetches https://<domain>/.well-known/trafficmorph-verify.txt (falling back to plain HTTP if HTTPS fails) and matches the file body against the verificationToken issued by :func:tm_add_domain — the same token DNS verification uses; there's only one token per domain. On match, the domain flips to verified=true.

Alternative to :func:tm_verify_domain_dns for users who can serve a static file at the target host but can't edit DNS.

Same fail-fast contract: misses return 400 with the expected URL + token in the message, not a "still pending" 200. The error message is constructed to be readable directly to the user (no JSON parsing required by the AI host).

Success response: VerifiedDomainResponse with verified=true, verifiedAt populated, and verificationMethod="HTTP" (uppercase — matches the server's stored value, see :func:tm_verify_domain_dns for the full set of method tokens).

Inputs: domain_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 25 tools

    Disambiguation5/5

    Each tool targets a distinct operation (domain management, profile CRUD, run lifecycle, capture analysis/import, variables set management) with no overlapping responsibilities. Even similar tools like tm_verify_domain_dns and tm_verify_domain_http are clearly differentiated by verification method.

    Naming Consistency5/5

    All tools follow a consistent 'tm_verb_noun' pattern (e.g., tm_add_domain, tm_get_run, tm_delete_variables_set). No mixing of naming conventions, and verbs are appropriately concise.

    Tool Count4/5

    25 tools is on the higher side but still well-scoped for a comprehensive traffic testing service covering domains, profiles, runs, captures, and variables sets. Each tool has a clear purpose, and no redundancy is apparent.

    Completeness4/5

    The tool surface covers core CRUD and lifecycle operations for all major entities. Minor gaps exist, such as no tool for updating variables set CSV content or managing alert policies, but these are mentioned as deliberately not exposed.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to programmatically create, execute, and analyze Apache JMeter performance tests. It supports automated bottleneck detection, report generation, and distributed testing management through natural language.
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Integrates Apache JMeter with AI assistants to run and manage load tests through natural language. It enables users to execute test plans, parse results, inspect test structures, and compare performance metrics across different runs.
      -