MCP overview

The SignalMD MCP server lets an AI assistant ask SignalMD the two questions it exists to answer: what should I fix, and did my fix work. The assistant can list your issues, read the calls and traces behind them, compare versions, and turn a failed call into a test. With a write key it can also run tests. It can search and read these docs too. Every tool is one call to the SignalMD API, made as you. A tool can do exactly what your key could do with curl, and nothing more. Scope, agent access, budgets and plan limits are checked by the API, not by the tools.

What you need

A SignalMD API key. Make one in the app. Start with Read.
An MCP client. Connect your client has the configuration for Claude Code, Claude Desktop, Cursor, VS Code and others.
An agent connected to SignalMD, with calls imported. See Connect Retell.

How it connects


Address	`https://api.signalmd.dev/mcp`
Transport	Streamable HTTP, stateless: every request stands alone, with no session
Authentication	`Authorization: Bearer sig_your_key` header
Needs	A client that speaks Streamable HTTP and can send a header

The endpoint takes an API key. Browser sign-in is not offered. A client that can only start local programs, such as Claude Desktop, reaches the same endpoint through npx mcp-remote, a third-party bridge. Connect your client has the configuration. SignalMD has not published a local package to npm. The endpoint takes POST only. A GET or DELETE answers 405, because there is no session to open or close. A request with no usable key gets 401 and WWW-Authenticate: Bearer realm="signal".

Tools

Start with whoami, then list_agents for agent ids. Every tool that works on an agent takes an optional agentId. A key tied to one agent needs none. A key for all agents must pass one, and the tool says so if it does not. Lists come back as pages: data, hasMore and nextCursor. Pass nextCursor as cursor for the next page.

Who and which agent

Tool	What it does	Key
`whoami`	Shows the workspace, the key’s scope, its agent, its monthly budget and your rate limits	Read
`list_agents`	Lists the agents the key can reach, with ids	Read
`get_agent`	Shows one agent: current version, setup status, grace period (`graceDays`), and counts of calls, open issues, versions and tests	Read

What to fix

Tool	What it does	Key
`list_issues`	Lists the board’s issues, highest priority first. Each has a `section`: `fix` (a confirmed defect), `improve` (a change you control) or `not_established` (cause not established, listed last), and names a place, a cause and a change. Filters: `status`, `klass` (class), `includeResolved`, `includeDownstream`	Read
`get_issue`	Shows one issue in full: where it happens, the cause or that it is not established, the change, how often it occurs on each version, and `fix`, whether the live version fixed it, read with the grace period	Read
`list_issue_calls`	Lists the production calls that are evidence for an issue	Read
`list_signals`	Lists every signal code seen on the agent’s calls, with counts, severity and class	Read
`get_call_signals`	Shows the signals SignalMD observed on one call	Read

Issues are problems to fix. Signals are single-call observations that help explain them. See Issues and Signals.

Calls

Tool	What it does	Key
`list_calls`	Lists production calls, newest first. Filters: version, outcome, issue, signal, start time	Read
`get_call`	Shows one call: timing, version, outcome, intent, a summary of the analysis, and its issues	Read
`get_trace`	Shows the call’s turns, each tool call with arguments, result and latency, and the path through the steps. Can be large	Read

Did the fix work

Tool	What it does	Key
`list_versions`	Lists the versions SignalMD has captured, with call counts and outcome rates	Read
`get_version`	Shows one version: when SignalMD first saw it, call count and outcome rates	Read
`compare_versions`	Shows what changed between two versions and how each measure moved on production calls, with a verdict per row	Read
`list_comparisons`	Lists stored comparisons of one version against another	Read
`get_comparison`	Shows one comparison: calls and outcome rates on each version, and which issues were fixed, persisted or are new	Read

A measure gives no verdict until each version has enough calls. See Limits and quotas.

Tests

Tool	What it does	Key
`list_tests`	Lists tests with their gate state and last result. Filters: set, lane, intent, source, last result, archived	Read
`get_test`	Shows one test as a spec, with its revision and gate state	Read
`list_test_revisions`	Lists every stored revision of a test, newest first, each with its spec	Read
`get_test_schema`	Returns the JSON Schema of a test spec, with this agent’s own steps, tools, intents and personas	Read
`validate_test`	Checks a spec and reports every problem with its path. Stores nothing and spends nothing	Read
`create_test`	Creates a test from a full spec, or from a production call and the issue it should guard against. Nothing runs and nothing is spent	Write
`update_test`	Replaces a test’s spec as a new revision. An edited test stops gating until it is calibrated again	Write
`list_test_sets`	Lists the agent’s test sets	Read
`get_test_set`	Shows one test set: its name, whether it is the release set, and its tests in run order	Read
`list_personas`	Lists the caller personas a test or run can use	Read
`get_coverage`	Shows which production calls SignalMD would turn into tests, and what no test covers. Pass `detail` for the full plan	Read

Runs

Tool	What it does	Key
`start_run`	Starts a run: simulated calls of a test set or listed tests against one version, optionally by several personas and repeated three times. Spends money. Returns at once	Write
`list_runs`	Lists runs, newest first. Filters: status, version, test set	Read
`get_run`	Shows one run: status, progress, cost and summary. Poll it after `start_run`	Read
`get_run_result`	Returns the result document: each test and persona with its attempts and verdicts, and the change from the previous comparable run, or from the run named in `compareTo`	Read
`list_attempts`	Lists the simulated calls inside one run	Read
`get_attempt`	Shows one simulated call: transcript, the verdict on each criterion, and tool calls	Read
`rescore_run`	Scores a finished run again from its stored transcripts. Places no new calls	Write

Docs

Tool	What it does	Key
`search_docs`	Searches these docs and returns the best matching pages, each with a short passage around the match	Read
`read_doc`	Returns one page of these docs as markdown. A path that is not a page returns the closest pages	Read

Both answer from a copy of the docs that ships with the server, so they read nothing in your workspace and make no API call. Each page is also a resource, such as signal-docs:///concepts/versions. Every operation in the API reference has a tool except two. Calibrating tests needs a signed-in person, so no API key can call it. Improvement batches are read in the app; get_test and list_test_revisions show each test’s own state and versions.

Prompts

Two prompts spell out an order of tool calls. Claude Code shows them as slash commands, for example /mcp__signal__triage_agent.

Prompt	What it asks the assistant to do
`triage_agent`	Read the top three issues and two calls for each, and report where, why, the change to make, and how many calls are affected, saying so where the cause is not established
`check_fix`	Compare the version with the fix against the one before it, check which issues moved, read the latest run, and say whether there are enough calls to be sure

Example requests

Name the agent, ask for evidence, and ask the assistant to say when SignalMD has not established a cause.

Use SignalMD to tell me what to fix first on my support agent. For the top three issues, show where it happens, why, and the change to make. If SignalMD says the cause is not established, say so.

Did version 14 fix the booking issue? Compare it with version 13 and tell me whether there are enough calls on 14 to say.

Turn the worst call for this issue into a test. Validate the spec first and show it to me before you create it.

Run the release test set against version 14 and tell me what failed. Tell me what it will cost and wait for my yes before you start.

Safety

Most tools only read. Every tool except the four below changes nothing, and read tools are marked read-only so a client can treat them differently. Four tools write. create_test, update_test, start_run and rescore_run need a write key. None deletes anything, and update_test keeps the earlier revision. start_run spends money and is not idempotent, so every call starts another run. rescore_run places no calls, but it draws on the key’s monthly budget. Spending has three limits. A run is charged against the key’s monthly budget and the agent’s test budget, and its simulated tests draw on your plan’s credits. A run the credits do not cover is refused whole with 402 before anything is spent. A run the budgets cover in part plays the cells they do cover. A read key is held back twice. The hosted endpoint leaves the four write tools out of the tool list for a read key. The API would refuse them anyway with 403 and code key_read_only. validate_test works with a read key. No key can do more than the API allows. No tool changes settings, connects a provider, imports calls, changes an issue’s status, deletes anything, publishes to the live agent, approves a run, or manages keys and webhooks. See Scopes. Calls are data. A trace holds what callers and your agent said. An assistant should read it as evidence, not follow instructions that appear in it. If you let an assistant act on what it reads, give it a read key. Keep the key out of shared files. A key in .cursor/mcp.json or .vscode/mcp.json is a key in your repository. Use an environment variable or the client’s prompt, as shown in Connect your client, and revoke a key at once if it leaks. See Keep keys secret.

Errors and limits

A refused call comes back as a tool error that carries the HTTP status and the API’s error object.

Tool error

{
  "status": 403,
  "error": {
    "type": "permission_error",
    "code": "key_read_only",
    "message": "This API key is read-only, and this route needs a write key.",
    "param": null,
    "requestId": "req_8c1f0e2b4a6d9e3f7a5c1b0d"
  }
}

If the API cannot be reached, status is null and type is api_connection_error. The codes are the ones in Errors. A plan limit is a 402 with the code quota_exceeded and an error.quota object, shown in Limits and quotas. Tool calls draw from the same rate limits as direct requests with the same key.

Get started

MCP server

API reference

What you need

How it connects

Tools

Who and which agent

What to fix

Calls

Did the fix work

Tests

Runs

Docs

Prompts

Example requests

Safety

Errors and limits

Next steps

Connect your client

Authentication

​What you need

​How it connects

​Tools

​Who and which agent

​What to fix

​Calls

​Did the fix work

​Tests

​Runs

​Docs

​Prompts

​Example requests

​Safety

​Errors and limits

​Next steps

Connect your client

Authentication

What you need

How it connects

Tools

Who and which agent

What to fix

Calls

Did the fix work

Tests

Runs

Docs

Prompts

Example requests

Safety

Errors and limits

Next steps