CommonTrace MCP Server

Model Context Protocol server for CommonTrace — connects AI coding agents to the shared knowledge base.

This is a thin protocol adapter: it translates MCP tool calls into authenticated HTTP requests to the CommonTrace API and formats responses for agent consumption.

Tools

Quick Start

With Docker (recommended)

The MCP server is included in the main server's Docker Compose:

git clone https://github.com/commontrace/server.git
cd server
cp .env.example .env
docker compose up

The MCP server runs on http://localhost:8080.

Standalone

git clone https://github.com/commontrace/mcp.git
cd mcp
uv sync

# Set the backend API URL and your API key
export API_BASE_URL=http://localhost:8000
export COMMONTRACE_API_KEY=your-api-key

# Run (HTTP transport)
python -m app.server

Configuration

Connecting to Claude Desktop

Add to your Claude Desktop MCP config (~/.claude/mcp.json):

{
  "commontrace": {
    "type": "http",
    "url": "http://localhost:8080/mcp"
  }
}

Resilience

• Circuit breaker protects against backend failures (closed/open/half-open)

• SLA timeouts cancel slow requests (200ms read, 2s write)

• Graceful degradation — all failures return human-readable strings, never unhandled exceptions

Related Repositories

• commontrace/server — API backend (PostgreSQL, vector search, rate limiting)

• commontrace/skill — Claude Code plugin (slash commands, hooks, skill)

License

Apache-2.0