MCP Server

Traceway speaks MCP (opens in a new tab) in two ways: the traceway CLI doubles as a local stdio server (traceway mcp), and every backend serves the same tools as a remote server at https://<your-instance>/mcp with OAuth login built in. Either way, MCP clients like Claude Code, Claude Desktop, and Cursor can investigate your production errors, logs, latency, and metrics directly.

The server is a thin layer over the same API client the CLI uses, and it ships the same operator playbooks the Traceway skill contains, exposed as MCP resources and prompts. One binary, one login, three surfaces.

Both servers described here are read only. A separate write server (/mcp/write, or traceway-write mcp) adds tools that archive issues, acknowledge pages, snooze alerts and edit post-mortems, behind write credentials and an organization opt-in. See Agent Write Access.

Remote server (zero install)

Point any streamable-HTTP MCP client at your instance and it handles login itself:

# Claude Code
claude mcp add --transport http traceway https://<your-instance>/mcp

On first use the client discovers the OAuth metadata, registers itself (RFC 7591 dynamic client registration), and opens your browser on the instance's consent page. Approve, and the client holds a short-lived access token plus a rotating refresh token; nothing to install or configure on the host.

Non-OAuth clients (or CI) can instead send a personal access token directly: Authorization: Bearer twp_... on every request.

/mcp never lists a write tool, whatever the credential. Agent credentials (personal access tokens and OAuth tokens) only reach the API routes the tools need; the rest of the dashboard API refuses them.

Two things differ from the local server: there is no default project (pass project_id, or let the model call list_projects first), and an unauthenticated request gets a 401 with a WWW-Authenticate challenge pointing at /.well-known/oauth-protected-resource/mcp, which is how spec-compliant clients find the login flow. The discovery documents and the /mcp endpoint answer CORS preflights, so browser-based clients (like the MCP Inspector auth debugger) can reach them too.

Local server (CLI session)

Log in and pick a default project once, in a terminal:

traceway login --url https://<your-instance>
traceway projects use <project-id>

Then register the server with your MCP client:

# Claude Code
claude mcp add traceway -- traceway mcp

For Claude Desktop, Cursor, or any other client, the command is traceway with the single argument mcp:

{
  "mcpServers": {
    "traceway": {
      "command": "traceway",
      "args": ["mcp"]
    }
  }
}

The server reuses the CLI session (including automatic token refresh for device logins) and the CLI's current project. If you are not logged in, traceway mcp exits immediately with instructions; log in in a terminal and reconnect.

Headless use (CI, containers)

Skip the CLI session entirely with environment variables:

Tools

Every tool wraps one API call and declares an output schema, so results come back as validated structuredContent alongside the JSON text. Every tool on this server is annotated read-only.

The write server adds archive_exceptions, unarchive_exceptions, acknowledge_page, resolve_page, set_notification_rule_enabled, snooze_notification_rule, run_check, create_post_mortem, update_post_mortem and set_slow_endpoint.

Project selection is per call: every project-scoped tool accepts a project_id parameter and falls back to the CLI's current project.

The by-id detail tools require the record's timestamp (recorded_at, or started_at for sessions) so lookups stay partition-pruned and fast, exactly like the CLI's --recorded-at flags. The tool descriptions teach agents where to recover it (dashboard URL ?t= params, occurrence lists, notifications).

Prompts and resources

The debugging knowledge lives in the server, not in the client:

• Prompts: debug_issue, investigate_performance, whats_broken, and resolve_notification render the full investigation playbooks with your argument inlined.
• Resources: traceway://knowledge/* documents cover the debug flow, the performance bottleneck checklist, dashboard URL resolution, timestamp recovery, notification handling, the product guide, and a CLI-to-tool map. The write server adds the write playbook (traceway://knowledge/operations).

These are the same documents the Traceway Claude Code skills are generated from, so the skills and the MCP server never disagree.

The product guide

traceway://knowledge/learn is a guide to every part of Traceway, with one resource per area:

The same guide ships as the traceway-learn skill, installed with the other skills (npx skills add tracewayapp/traceway --all, or the tw Claude Code plugin). Ask an agent how paging escalates, why an endpoint is Critical, or how to put a status page on your own domain, and it answers from the guide.

Errors

Tool errors carry the CLI's stable error codes in the text, formatted as error=<code>: <message>. Hint: <hint>, so agents can branch on token_expired, not_found, rate_limited, no_project, and friends. A forbidden error carries the server's reason, such as a read-only credential or agent writes being turned off.