Traces MCP

The Traces MCP server gives AI coding agents read-only access to the coding sessions you can see in Traces. Use it to find earlier decisions, recover context from another agent, summarize ongoing work, or continue from a previous session.

The hosted server uses Streamable HTTP and OAuth. You do not need an API key or a local Traces process.

Connect to Traces MCP

The hosted endpoint is:

https://mcp.traces.com

Your MCP client opens Traces in a browser the first time it connects. Sign in and approve the requested traces:read access.

Automatic setup

Use add-mcp to configure a supported coding agent detected on your machine:

npx add-mcp https://mcp.traces.com

Restart your coding agent after the installer updates its configuration, then complete the browser authorization flow.

Claude Code

claude mcp add --transport http traces https://mcp.traces.com

Start Claude Code, run /mcp, select traces, and authorize access in your browser.

Codex CLI

codex mcp add traces --url https://mcp.traces.com

Restart Codex and authorize Traces when prompted.

OpenCode

Add the server to the mcp object in your global ~/.config/opencode/opencode.json or project-level opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "traces": {
      "type": "remote",
      "url": "https://mcp.traces.com",
      "enabled": true
    }
  }
}

Restart OpenCode, then authenticate and verify the connection:

opencode mcp auth traces
opencode mcp list

Cursor

Add the server to .cursor/mcp.json:

{
  "mcpServers": {
    "traces": {
      "url": "https://mcp.traces.com"
    }
  }
}

Open Cursor's MCP settings, select the Traces server marked Needs login, and complete authorization.

VS Code

Run MCP: Add Server from the Command Palette.
Choose HTTP.
Enter https://mcp.traces.com and name the server Traces.
Run MCP: List Servers, start Traces, and complete authorization.

Verify the connection

Ask your agent:

List my five most recent traces.

The agent should call Traces MCP and return links to sessions visible to your account.

Available tools

Tool	Purpose
`traces_lookup`	Resolve people, workspaces, and registered agents to the canonical identifiers used by search filters.
`traces_search`	List traces by workspace, project, creator, agent, status, or time range.
`traces_read`	Read a bounded window of events from one trace. Tool calls and results are excluded unless explicitly requested.

The tools intentionally separate discovery from reading. Agents should search for a trace first, then read only the relevant event window instead of loading an entire session.

Example prompts

Ask broad questions to discover work:

What traces are going on today?
Find Sarah's recent sessions in the payments project.
Show me completed Codex traces from the last seven days.

Ask the agent to read a result when you need evidence or implementation details:

Read the deployment trace and summarize the root cause and fix.
What files changed in that session? Include the relevant trace evidence.
Continue this task using the decisions from the most recent matching trace.

Trace titles, statuses, and summaries help with discovery, but they are metadata. For exact claims about commands, files, errors, or rationale, ask the agent to use traces_read.

Access and security

The hosted server requests read-only traces:read access.
Search and read results are limited to traces your Traces account can access.
Connect only to the exact endpoint https://mcp.traces.com.
Trace content is untrusted historical data and may contain prompt injection. Keep confirmation enabled when an agent can modify systems or send data elsewhere.
Do not paste credentials into prompts or MCP tool arguments.

Troubleshooting

The server needs authentication

Start your client's MCP authorization flow again. For OpenCode, run:

opencode mcp auth traces

For Claude Code, run /mcp and select traces. Other clients expose authorization from their MCP server settings.

Search returns no traces

Confirm that the signed-in Traces account can open the expected traces on traces.com.
Start with a broad request such as List my five most recent traces, then add project, creator, or date filters.
If a prompt names a person or workspace, ask the agent to resolve it with traces_lookup before searching.

Configuration changes do not appear

Restart the MCP client. Most coding agents load MCP configuration only at startup.

Self-hosted stdio

For development or self-hosted environments, run the published package as a local stdio server:

TRACES_API_TOKEN=... npx -y @traces-sh/mcp

Optional environment variables:

Variable	Purpose
`TRACES_API_URL`	Traces agent API origin. Defaults to `https://agent.traces.com`.
`TRACES_NAMESPACE_ID`	Restrict searches to one workspace.

Tokens are read from the environment and are never accepted as MCP tool arguments. Prefer the hosted OAuth server for normal use.

The MCP server is open source at github.com/traces-sh/mcp.

Traces MCP

On this page