Connect an agent

This page lets you connect an AI coding agent to Spectrace over the Model Context Protocol (MCP), so the agent can read requirements, update acceptance criteria and test cases, and verify a diff against a requirement.

The Spectrace MCP server (@spectrace/mcp-server, binary spectrace-mcp) exposes tools, templated resources and prompts to any MCP client. The full list of tools is on the Tool reference.

Prerequisites

A Spectrace account and an API key from Settings → Developers. See API keys.
An MCP client. Claude Code and Cursor send the API key as an HTTP header; Claude Desktop reaches the hosted endpoint through a local bridge process.
For the hosted endpoint: an organization on a paid plan. A Free-plan key can call only spectrace_whoami and spectrace_capabilities; every other tool returns an error saying agent access is not included on the free plan.

Choose a connection path

Path	When to use it	Auth
Hosted — `https://spectrace.io/api/mcp`	You are a Spectrace customer and your client can send a header. No install, no database credentials.	`Authorization: Bearer spc_k1_…` on every request
Local stdio — `node packages/mcp-server/dist/cli.js` from a checkout	You work inside the Spectrace monorepo, or run your own database.	`SPECTRACE_API_KEY` in the process environment, plus `DATABASE_URL`
Self-hosted HTTP — Docker on port `3333`	Fully isolated or on-premises deployment.	`Authorization: Bearer spc_k1_…` on every request, plus `DATABASE_URL` in the container

The hosted endpoint speaks Bearer API keys only and does not support OAuth. Clients that cannot send a header or run a local bridge — claude.ai in the browser, Claude mobile — have no hosted path today.

Hosted endpoint

The server runs inside the deployed web app at https://spectrace.io/api/mcp and authenticates each request with your API key. Replace spc_k1_… with the key you created.

Run this in any terminal:

bash

claude mcp add spectrace --transport http https://spectrace.io/api/mcp \
  --header "Authorization: Bearer spc_k1_…"

Claude Desktop's connector dialog does not accept an API key header without a bridge, so bridge the endpoint with mcp-remote. Open Settings → Developer → Edit Config and add:

json

{
  "mcpServers": {
    "spectrace": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@0.1.38",
        "https://spectrace.io/api/mcp",
        "--header",
        "Authorization:${SPECTRACE_AUTH}"
      ],
      "env": { "SPECTRACE_AUTH": "Bearer spc_k1_…" }
    }
  }
}

Then fully quit and reopen Claude Desktop. Things that bite:

Keep the header as "Authorization:${SPECTRACE_AUTH}" with the value in env. This is the form the in-app snippet emits.
Keep the literal Bearer in the env value. A bare spc_k1_… sends Authorization: spc_k1_… and gets a 401.
A browser window opening means a bad key, not OAuth. Spectrace's 401 carries no WWW-Authenticate header and the endpoint offers no OAuth flow. Fix the key.
spawn npx ENOENT means Claude Desktop cannot see your shell's PATH. Run which npx and paste the absolute path as command. Logs are at ~/Library/Logs/Claude/mcp-server-spectrace.log.
Keep the version pinned to mcp-remote@0.1.38 — the same pin the in-app snippet uses; @latest runs unreviewed code on every launch.

The key sits in plaintext in claude_desktop_config.json, so use a dedicated key you can revoke.

Save as .cursor/mcp.json in your project:

json

{
  "mcpServers": {
    "spectrace": {
      "url": "https://spectrace.io/api/mcp",
      "headers": { "Authorization": "Bearer spc_k1_…" }
    }
  }
}

The same three snippets, filled in with your deployment's origin, are available in the app under Settings → Developers → Connect an AI agent. The in-app picker offers those three clients only; there is no verified configuration for VS Code's native MCP support.

Smoke-test the endpoint without a client:

bash

curl -X POST https://spectrace.io/api/mcp \
  -H "Authorization: Bearer spc_k1_…" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

A valid key returns a JSON-RPC response listing every spectrace_* tool. A missing, invalid or expired key returns HTTP 401 with a JSON-RPC error whose data.reason is MISSING_API_KEY, INVALID_API_KEY or API_KEY_EXPIRED.

Local stdio from a checkout

Local stdio runs the server as your own process. It talks to Postgres directly, so it needs DATABASE_URL, which makes it a developer or self-host path rather than something to hand to a customer. AI-backed tools (extraction, ambiguity analysis, test generation, inline PR verification, semantic search) also need OPENAI_API_KEY in the process environment.

Build the server
From the repository root:
bashruns in CI
```
pnpm --filter @spectrace/mcp-server build
node packages/mcp-server/dist/cli.js --version
```
The second command prints the server version. dist/ is git-ignored, so rebuild after pulling changes.

Point your client at the built entry

Use the absolute path to your checkout. start is the default command and stdio is the default transport. Pass start explicitly anyway: with no arguments at all the CLI also prints its help text to stdout before starting, and that text lands on the MCP channel.

~/Library/Application Support/Claude/claude_desktop_config.json:

json

{
  "mcpServers": {
    "spectrace": {
      "command": "node",
      "args": ["/absolute/path/to/spectrace/packages/mcp-server/dist/cli.js", "start"],
      "env": {
        "SPECTRACE_API_KEY": "spc_k1_…",
        "DATABASE_URL": "postgres://…"
      }
    }
  }
}

Restart Claude Desktop, then ask it to call spectrace_whoami to confirm the tools are available.

bash

claude mcp add spectrace \
  --env SPECTRACE_API_KEY=spc_k1_... \
  --env DATABASE_URL=postgres://... \
  -- node /absolute/path/to/spectrace/packages/mcp-server/dist/cli.js start

Read tools carry readOnlyHint and the two delete tools (spectrace_requirements_delete, spectrace_testcases_delete) carry destructiveHint, so clients that honour MCP tool annotations can auto-allow reads and prompt on deletes.

.cursor/mcp.json:

json

{
  "mcpServers": {
    "spectrace": {
      "command": "node",
      "args": ["/absolute/path/to/spectrace/packages/mcp-server/dist/cli.js", "start"],
      "env": {
        "SPECTRACE_API_KEY": "spc_k1_...",
        "DATABASE_URL": "postgres://..."
      }
    }
  }
}

Check the configuration
node packages/mcp-server/dist/cli.js validate loads the configuration, runs SELECT 1 against the database and validates the API key, then exits. node packages/mcp-server/dist/cli.js config prints the resolved configuration with secrets masked.

The start command also accepts -k, --api-key <key> instead of the env var, and -v, --verbose for debug logging. Env vars the process reads: DATABASE_URL (required), SPECTRACE_API_KEY (alias SPECTRACE_MCP_API_KEY), SPECTRACE_LOG_LEVEL, SPECTRACE_RATE_LIMIT, SPECTRACE_TIMEOUT, SPECTRACE_MCP_TRANSPORT, SPECTRACE_MCP_HTTP_HOST, SPECTRACE_MCP_HTTP_PORT. A .env file in the working directory is loaded automatically.

Development fallback without an API key

Against a development database you can skip the API key and set SPECTRACE_USER_ID, SPECTRACE_ORG_ID, and optionally SPECTRACE_USER_ROLE (default member) with DATABASE_URL. The server logs Authenticated via env vars (development mode) and uses those values for every call. This mode is refused when NODE_ENV=production unless SPECTRACE_ALLOW_DEV_AUTH=1 is set, because it skips key validation entirely.

Self-hosted HTTP

The same server runs as a multi-tenant HTTP service, authenticating each request with a Bearer API key exactly like the hosted endpoint. Build the image from a checkout and run it with your database URL:

bash

docker build -t spectrace-mcp -f packages/mcp-server/Dockerfile .
 
docker run --rm \
  -e DATABASE_URL=postgres://… \
  -p 3333:3333 \
  spectrace-mcp

The container sets SPECTRACE_MCP_TRANSPORT=http and listens on 0.0.0.0:3333. GET / and GET /health answer {"status":"ok","transport":"http"} without authentication for load balancers; every other request must carry Authorization: Bearer spc_k1_…. Point clients at http://<host>:3333/mcp using the hosted snippets above with the URL swapped. Terminate TLS with a reverse proxy in front of the container.

Without Docker, the equivalent is node packages/mcp-server/dist/cli.js start --http --port 3333 (--host defaults to 127.0.0.1).

Confirm it works

Ask your agent to call spectrace_whoami. It returns the user, organization, role and effective permissions behind the key, plus up to ten recent projects with their IDs. Both spectrace_whoami and spectrace_capabilities work on every plan and never count against the plan allowance.

spectrace_capabilities returns the tool catalog with each tool's input schema, the six resource templates, and the caller's permissions — useful for a first-call discovery step.

You are done when spectrace_whoami returns your organization and a non-empty permission list. If it fails:

Symptom	Cause	Fix
`MISSING_API_KEY` on stdio	env not set	Set `SPECTRACE_API_KEY` (or the dev fallback vars) in the client's `env` block.
HTTP 401, reason `INVALID_API_KEY`	wrong, revoked, or the user left the org	Check the key under Settings → Developers; create a new one.
HTTP 401, reason `API_KEY_EXPIRED`	key past its expiry	Create a new key.
`INSUFFICIENT_PERMISSIONS`	your org role does not cover the tool's scope	Ask an org admin to change your role.
A tool returns "agent access isn't included on the free plan"	Free plan	Upgrade the organization.
`DATABASE_URL environment variable is required`	stdio or self-hosted started without a database URL	Set `DATABASE_URL`.

Rate limits and quotas

Tool calls: 100 per minute per user by default, enforced in the server with an in-memory sliding window. Exceeding it returns a tool error Rate limit exceeded. Try again in N seconds. Self-hosted deployments change it with SPECTRACE_RATE_LIMIT. Resource reads pass the same gate.
Hosted endpoint, HTTP layer: the web app also limits requests to 300 per minute per Bearer token. Exceeding it returns HTTP 429 with a JSON-RPC error whose data.reason is RATE_LIMIT_EXCEEDED and a Retry-After: 60 header.
Plan allowance: paid plans include a monthly agent-call allowance per organization. When it is reached, tool calls return an error stating the allowance and plan until the next billing period. spectrace_whoami and spectrace_capabilities are exempt.
Timeout: each tool call is cut off after 30 seconds by default (SPECTRACE_TIMEOUT for stdio and self-hosted).

Tool reference — every tool, its arguments and annotations, generated from the server.
Verify before you push — run inline PR verification from the agent.
API keys — create, revoke and understand what a key authenticates.
Roles and permissions — which org roles map to which tool scopes.