MCP Sidecar

Overview

The Primer MCP sidecar is a Model Context Protocol server that gives Claude Code direct access to your team’s usage data during conversations — no context switching required. Ask Claude about your team’s patterns, friction points, or cost trends, and it queries Primer inline and returns insights in the conversation.

The sidecar runs locally alongside Claude Code, one instance per developer machine. It has no persistent state — all data lives in the Primer API server.

The 5 Tools

Tool	Signature	Auth	What it does
sync	sync()	PRIMER_API_KEY	Upload local sessions not yet synced to the server
my_stats	my_stats(days=30)	PRIMER_API_KEY	Personal analytics: session counts, token usage, tools, outcomes
team_overview	team_overview(team_id?)	PRIMER_ADMIN_API_KEY	Team aggregate usage, costs, and outcome distribution
friction_report	friction_report(team_id?)	PRIMER_ADMIN_API_KEY	Friction points by type and frequency
recommendations	recommendations(team_id?)	PRIMER_ADMIN_API_KEY	Actionable recommendations based on usage patterns

sync

Scans your local Claude Code transcript directory for sessions that haven’t been uploaded to the Primer server. Useful after working offline or if the server was down when sessions ended. Returns a summary of how many sessions were found and uploaded.

my_stats

Returns your personal usage statistics for the last N days (default 30). Includes session count, total tokens, tool usage breakdown, outcome distribution, and estimated cost. Uses your engineer API key to identify you.

team_overview

Provides team-level aggregate analytics. Pass an optional team_id to scope to a specific team, or omit it for organization-wide stats. Requires admin-level access since it spans multiple engineers.

friction_report

Shows the most common friction points your team encounters, ranked by frequency. Friction categories include permission denials, tool failures, context limits, and other blockers. Useful for identifying systemic issues.

recommendations

Returns actionable recommendations generated from your team’s usage patterns and friction analysis. These might include configuration changes, workflow improvements, or training suggestions.

Registration

Add the sidecar to your Claude Code MCP configuration in ~/.claude/settings.json:

{
  "mcpServers": {
    "primer": {
      "command": "python",
      "args": ["-m", "primer.mcp.server"],
      "env": {
        "PRIMER_SERVER_URL": "http://localhost:8000",
        "PRIMER_API_KEY": "primer_...",
        "PRIMER_ADMIN_API_KEY": "your-admin-key"
      }
    }
  }
}

After saving, restart Claude Code. The five Primer tools will appear in Claude’s available tool list.

Environment Variables

Variable	Used by	Purpose
PRIMER_SERVER_URL	All tools	Base URL of the Primer API server
PRIMER_API_KEY	sync, my_stats	Your personal engineer API key
PRIMER_ADMIN_API_KEY	team_overview, friction_report, recommendations	Admin key for accessing team-wide data

Example Conversations

Once the sidecar is registered, you can ask Claude questions naturally and it will call the appropriate Primer tools:

Personal stats:

“How many sessions did I have this week?”

Claude calls my_stats(days=7) and summarizes your activity.

Team comparison:

“How does the Backend team’s token usage compare to last month?”

Claude calls team_overview(team_id="backend-team-id") and provides a comparison.

Friction analysis:

“What’s causing the most friction across our team?”

Claude calls friction_report() and highlights the top friction categories with counts.

Workflow improvement:

“What recommendations do you have for improving our AI workflow?”

Claude calls recommendations() and presents actionable suggestions.

Sync and review:

“Sync my recent sessions and show me my stats.”

Claude calls sync() first, then my_stats(), and presents a combined summary.

Internal Architecture

The sidecar is built with FastMCP and communicates with the Primer REST API over HTTP using httpx.

Claude Code
  └── MCP tool call (e.g., team_overview)
        └── primer.mcp.tools.primer_team_overview()
              └── httpx GET /api/v1/analytics/overview
                    └── Returns JSON string to Claude

Each tool function:

1. Checks that the required API key environment variable is set.
2. Makes an HTTP request to the appropriate Primer API endpoint with auth headers.
3. Returns the JSON response as a string for Claude to interpret and present.

All tools use a 10-second HTTP timeout. If the server is unreachable, the tool returns a descriptive error message that Claude can relay to you.

Source Files

The MCP implementation lives in two files:

• src/primer/mcp/server.py — FastMCP app definition and @mcp.tool() registration for all five tools.
• src/primer/mcp/tools.py — Tool function implementations with httpx calls and error handling.

Auth Header Construction

The sidecar sends both x-admin-key and x-api-key headers on requests that need admin access. The admin key is resolved as PRIMER_ADMIN_API_KEY with fallback to PRIMER_API_KEY:

def _admin_headers() -> dict:
    admin_key = ADMIN_API_KEY or API_KEY
    return {"x-admin-key": admin_key, "x-api-key": API_KEY}

Running Manually

You can run the MCP server directly for testing or debugging:

PRIMER_SERVER_URL=http://localhost:8000 \
PRIMER_API_KEY=primer_... \
PRIMER_ADMIN_API_KEY=your-admin-key \
python -m primer.mcp.server

This starts the FastMCP server and listens for tool calls over stdin/stdout, the standard MCP transport.

Troubleshooting

”PRIMER_API_KEY not set”

The sidecar cannot find your engineer key. Make sure PRIMER_API_KEY is set in the env block of your MCP config in ~/.claude/settings.json.

”Error connecting to server”

The MCP sidecar cannot reach your Primer server. Verify:

1. PRIMER_SERVER_URL is correct in your MCP config.
2. The server is running: curl http://localhost:8000/health
3. No firewall is blocking the connection.

Tools not appearing in Claude

Claude Code reads MCP configuration at startup. After editing ~/.claude/settings.json:

1. Fully quit Claude Code (not just close the window).
2. Relaunch Claude Code.
3. The Primer tools should appear in the tool list.

If tools still don’t appear, check for JSON syntax errors in your settings file:

python -m json.tool < ~/.claude/settings.json

Team tools returning 403

The team_overview, friction_report, and recommendations tools require admin-level access. Make sure PRIMER_ADMIN_API_KEY is set to a valid admin key, not an engineer key.