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

Related MCP server: UseCortex MCP Server

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