MCP server

Overview

Ghit 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 Ghit 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://ghit.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 17 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://ghit.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 Ghit MCP server to Claude Code:

claude mcp add --transport http --header "Authorization: Bearer $GHIT_API_TOKEN" ghit $GHIT_API_URL/v1/mcp

Codex CLI

Add the Ghit MCP server to Codex. You must export $GHIT_API_TOKEN in your environment.

codex mcp add --url $GHIT_API_URL/v1/mcp --bearer-token-env-var GHIT_API_TOKEN ghit

Gemini CLI

Add the Ghit MCP server to Gemini:

gemini mcp add --transport http --header "Authorization: Bearer $GHIT_API_TOKEN" ghit $GHIT_API_URL/v1/mcp

Editors and IDEs

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

• Server URL: https://your-ghit-instance/api/v1/mcp
• Transport: Streamable HTTP
• Authentication: Bearer token via Authorization header

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

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