> ## Documentation Index > Fetch the complete documentation index at: https://docs.signalmd.dev/llms.txt > Use this file to discover all available pages before exploring further. # MCP overview > Give Claude, Cursor or another AI assistant access to your Signal issues, calls, versions and tests, with read access by default. The Signal MCP server lets an AI assistant ask Signal 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 [Signal API](/api/introduction), 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 Signal API key. [Make one in the app](/api/authentication#make-a-key). Start with **Read**. * An MCP client. [Connect your client](/mcp/clients) has the configuration for Claude Code, Claude Desktop, Cursor, VS Code and others. * An agent connected to Signal, with calls imported. See [Connect Retell](/guides/connect-retell). ## How it connects | | | | - | - | | Address | `https://first-signal-api.fly.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](/mcp/clients) has the configuration. Signal 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 Signal observed on one call | Read | Issues are problems to fix. Signals are single-call observations that help explain them. See [Issues](/concepts/issues) and [Signals](/concepts/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 Signal has captured, with call counts and outcome rates | Read | | `get_version` | Shows one version: when Signal 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](/limits#version-comparisons). ### 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 Signal 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](/api/introduction#resources) has a tool except calibrating tests, which needs a signed-in person. No API key can call it. ## 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 Signal has not established a cause. > Use Signal 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 Signal 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 and the workspace's [AI model allowance](/limits#plan-limit-errors). **Spending has three limits.** A run is charged against the key's monthly budget and the agent's test budget, and its simulated calls count against your plan's allowance. A run the plan does 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](/api/authentication#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](/mcp/clients), and revoke a key at once if it leaks. See [Keep keys secret](/api/authentication#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. ```json Tool error theme={null} { "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](/api/introduction#errors). A plan limit is a `402` with the code `quota_exceeded` and an `error.quota` object, shown in [Limits and quotas](/limits#plan-limit-errors). Tool calls draw from the same [rate limits](/limits#api-rate-limits) as direct requests with the same key. ## Next steps Copy the configuration for Claude Code, Claude Desktop, Cursor or VS Code. Make a key and choose read or write. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.