{% extends "docs/base.html" %} {% block docs_content %}

MCP server

Use the Model Context Protocol to connect AI coding agents directly to Pearing.

API docs CLI docs File uploads docs Skills docs Work docs MCP docs

Overview

Pearing exposes an MCP server at POST /api/v1/mcp using the Streamable HTTP transport with JSON-RPC 2.0 framing. It provides task-shaped tools that let AI agents read repo context, participate in threads and pull reviews, and stream real-time events without needing the REST API or CLI.

The MCP server shares the same authentication, authorization, and event emission as the REST API. All tool responses use the same v1 API resource shapes.

Authentication

All MCP requests require a Pearing API token passed as a Bearer token in the Authorization header: 

Authorization: Bearer YOUR_API_TOKEN

Create an API token from your profile page or via the CLI. The token determines which user the MCP tools act as.

Protocol

The MCP server supports the standard MCP protocol handshake:

  1. Send initialize with your client info and capabilities
  2. Receive server capabilities and protocol version
  3. Send notifications/initialized
  4. Call tools/list to discover available tools
  5. Call tools/call to invoke tools
curl -X POST https://pearing.example/api/v1/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

The server also supports ping for keepalive checks.

Available tools

The MCP server exposes 36 tools. Browse the individual tool pages in the sidebar for parameters, examples, and response shapes.

Event streaming

GET /api/v1/mcp opens an SSE stream of real-time events filtered to the authenticated user's scopes. This uses the same backfill-then-live infrastructure as the tail-events API. 

curl -N https://pearing.example/api/v1/mcp?scope=user:myusername \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Query parameters: scope (defaults to the authenticated user), kind (event kind filter), last_event_id (resume from ID).

Claude Code CLI

Add the Pearing MCP server to Claude Code: 

claude mcp add --transport http --header "Authorization: Bearer $PEARING_API_TOKEN" pearing $PEARING_API_URL/v1/mcp

Codex CLI

Add the Pearing MCP server to Codex. You must export $PEARING_API_TOKEN in your environment. 

codex mcp add --url $PEARING_API_URL/v1/mcp --bearer-token-env-var PEARING_API_TOKEN pearing

Gemini CLI

Add the Pearing MCP server to Gemini: 

gemini mcp add --transport http --header "Authorization: Bearer $PEARING_API_TOKEN" pearing $PEARING_API_URL/v1/mcp

Editors and IDEs

Any MCP-capable editor or IDE can connect to the Pearing MCP server. The configuration varies by tool, but the connection details are always:

For VS Code with an MCP extension, add to your workspace settings: 

{
  "mcp.servers": {
    "pearing": {
      "type": "url",
      "url": "https://pearing.example/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}
{% endblock %}