MCP Server

Overview

Retrace provides a Model Context Protocol (MCP) server that lets AI coding agents search traces, recall memories, and inspect past executions directly from their IDE. This bridges your observability data with your development workflow — agents can learn from previous runs without leaving the editor.

Setup

Add Retrace to your MCP configuration file:

Claude Code (.claude/mcp.json):

{
  "mcpServers": {
    "retrace": {
      "command": "npx",
      "args": ["@retrace/api", "mcp"],
      "env": {
        "DATABASE_URL": "postgresql://...",
        "GEMINI_API_KEY": "AIza..."
      }
    }
  }
}

Cursor (Settings → MCP Servers):

Use the same configuration format. Cursor reads MCP server definitions identically.

Windsurf (.windsurf/mcp.json):

{
  "mcpServers": {
    "retrace": {
      "command": "npx",
      "args": ["@retrace/api", "mcp"],
      "env": {
        "DATABASE_URL": "postgresql://...",
        "GEMINI_API_KEY": "AIza..."
      }
    }
  }
}

Environment Variables

Available Tools

Example Prompts

Once configured, ask your AI coding agent natural-language questions:

• "What traces failed recently?" → calls list_traces with status: "failed"
• "Search for spans where the agent called web_search" → calls search_spans
• "Remember that the user prefers TypeScript" → calls store_memory
• "What do we know about the API rate limits?" → calls recall_memories
• "Show me the demo tape" → calls get_tape

Use Cases

Debugging — When an agent run fails, ask your coding agent to pull the trace and inspect which span errored. It can read inputs, outputs, and error messages without you opening the dashboard.

Knowledge persistence — Store architectural decisions, user preferences, or project conventions as memories. Your coding agent recalls them in future sessions automatically.

Learning from history — Search past successful traces to understand how a workflow executed, then replicate or improve the pattern.

Troubleshooting

[!NOTE] The MCP server runs locally and connects directly to your database. No data is sent to Retrace cloud servers — all queries execute against your own PostgreSQL instance.