Agent Client Protocol (ACP) Integration

CodeGraph supports the Agent Client Protocol (ACP) for seamless IDE integration with Zed, JetBrains IDEs, VS Code, and other ACP-compatible editors.

Overview¶

ACP is a standardized protocol for communication between code editors and AI coding agents. CodeGraph implements ACP to provide intelligent code analysis directly within your IDE.

Transports¶

CodeGraph supports three transport mechanisms:

Transport	Use Case	Endpoint
stdio	Local subprocess (IDE spawned)	`codegraph-acp` command
HTTP	Remote REST API	`POST /api/v1/acp/rpc`
WebSocket	Real-time streaming	`WS /api/v1/acp/ws`

Supported Methods¶

Baseline Methods (Required)¶

Method	Description
`initialize`	Capability negotiation
`authenticate`	JWT token authentication
`session/new`	Create new session
`session/prompt`	Send user message
`session/cancel`	Cancel ongoing operation

Optional Methods¶

Method	Description
`session/load`	Resume existing session
`fs/read_text_file`	Read file from filesystem
`fs/write_text_file`	Write file to filesystem
`terminal/create`	Create terminal session
`terminal/output`	Get terminal output
`terminal/wait_for_exit`	Wait for command completion
`terminal/kill`	Kill running command
`terminal/release`	Release terminal resources

Thread Management Methods¶

Method	Description
`thread/start`	Start a new conversation thread
`thread/resume`	Resume an existing thread
`thread/fork`	Fork a thread into a new branch
`thread/list`	List all active threads
`thread/archive`	Archive a completed thread
`thread/compact`	Compact thread history

Turn Control Methods¶

Method	Description
`turn/start`	Begin a new agent turn
`turn/interrupt`	Interrupt current turn

Diagnostics Methods¶

Method	Description
`diagnostics/subscribe`	Subscribe to diagnostic events
`diagnostics/unsubscribe`	Unsubscribe from diagnostics

IDE Integration Methods¶

Method	Description
`hover/request`	Request hover information for symbol
`item/fileChange/respondApproval`	Respond to file change approval request

Agent Capabilities¶

CodeGraph advertises the following capabilities:

{
  "loadSession": true,
  "setMode": false,
  "promptCapabilities": {
    "image": false,
    "audio": false,
    "embeddedContext": true
  },
  "mcp": {
    "stdio": true,
    "http": true,
    "sse": false
  },
  "authMethods": ["bearer"]
}

Session Lifecycle¶

1. Initialize
   Client -> initialize -> Agent
   Agent -> capabilities -> Client

2. Create Session
   Client -> session/new {cwd} -> Agent
   Agent -> {sessionId} -> Client

3. Send Prompt
   Client -> session/prompt {sessionId, prompt} -> Agent
   Agent -> session/update (plan) -> Client
   Agent -> session/update (tool_call) -> Client
   Agent -> session/update (agent_message_chunk) -> Client
   Agent -> {stopReason} -> Client

4. Close
   Client -> session/cancel -> Agent

API Endpoints¶

HTTP Transport¶

POST /api/v1/acp/rpc

Single JSON-RPC endpoint for all ACP method calls.

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": 1,
    "clientCapabilities": {},
    "clientInfo": {"name": "my-ide", "version": "1.0"}
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": 1,
    "agentCapabilities": {...},
    "agentInfo": {
      "name": "codegraph",
      "version": "0.1.0",
      "title": "CodeGraph AI-native Code Analysis Agent"
    }
  }
}

WebSocket Transport¶

WS /api/v1/acp/ws?token=

Streaming endpoint with real-time session updates.

Supports bidirectional messaging: - Client -> Agent: JSON-RPC requests - Agent -> Client: JSON-RPC responses + notifications

Health Check¶

GET /api/v1/acp/health

Returns agent status and capabilities.

GET /api/v1/acp/info

Returns agent metadata for discovery.

Session Management and Stats¶

GET /api/v1/acp/sessions

Returns active ACP sessions for the current user. Authentication required.

DELETE /api/v1/acp/sessions/{session_id}

Deletes an ACP session owned by the current user. Authentication required. Returns 404 if the session does not exist, 403 if the user is not the owner.

GET /api/v1/acp/stats

Returns ACP runtime statistics: - Session stats - WebSocket connection count - Active terminal count

Authentication required.

Session Updates¶

During prompt processing, CodeGraph sends session/update notifications:

Plan Update¶

{
  "sessionUpdate": "plan",
  "plan": {
    "entries": [
      {"id": "1", "title": "Classifying intent", "status": "completed"},
      {"id": "2", "title": "Querying code graph", "status": "in_progress"},
      {"id": "3", "title": "Generating response", "status": "pending"}
    ]
  }
}

Tool Call Update¶

{
  "sessionUpdate": "tool_call",
  "toolCallId": "tc_abc123",
  "title": "Security Analysis",
  "kind": "search",
  "status": "in_progress"
}

Message Chunk¶

{
  "sessionUpdate": "agent_message_chunk",
  "chunk": "Based on my analysis..."
}

Tool Call Kinds¶

CodeGraph maps its scenarios to ACP tool kinds:

Scenario	Tool Kind
Security Analysis	search
Code Review	read
Performance Analysis	search
Refactoring	edit
Documentation	read
Architecture Analysis	think

Authentication¶

For HTTP/WebSocket transports, authentication is optional but recommended:

Authorization: Bearer <jwt_token>

Authenticated sessions have: - Persistent dialogue history - User-specific settings - Rate limit quotas

Error Codes¶

Code	Meaning
-32700	Parse error
-32600	Invalid request
-32601	Method not found
-32602	Invalid params
-32603	Internal error
-32002	Agent not initialized

Examples¶

Initialize and Create Session¶

# Initialize
curl -X POST http://localhost:8000/api/v1/acp/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": 1,
      "clientCapabilities": {},
      "clientInfo": {"name": "curl-client"}
    }
  }'

# Create session
curl -X POST http://localhost:8000/api/v1/acp/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "session/new",
    "params": {"cwd": "/path/to/project"}
  }'

Send Prompt¶

curl -X POST http://localhost:8000/api/v1/acp/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "session/prompt",
    "params": {
      "sessionId": "acp_xxx",
      "prompt": [
        {"type": "text", "text": "What are the main entry points?"}
      ]
    }
  }'

MCP Server Support¶

CodeGraph can connect to external MCP servers provided by the client:

{
  "method": "session/new",
  "params": {
    "cwd": "/project",
    "mcpServers": [
      {
        "id": "github",
        "name": "GitHub MCP",
        "transport": "stdio",
        "command": "github-mcp-server"
      }
    ]
  }
}

CodeGraph MCP Server¶

CodeGraph also exposes its own MCP server, allowing AI assistants (Claude Code, Cursor, Windsurf, etc.) to query the Code Property Graph directly.

Running the Server¶

# Start MCP server via stdio transport
python -m src.mcp

# With specific database
python -m src.mcp --db data/projects/postgres.duckdb

# Verbose logging
python -m src.mcp --verbose

Available Tools (65 tools)¶

The MCP server exposes 65 built-in tools covering code analysis, navigation, security, compliance, structural patterns, enterprise integrations, and more.

For the complete tool reference with parameters and descriptions, see MCP Tools Reference.

Configuration¶

MCP server settings in config.yaml:

mcp:
  enabled: true
  transport: stdio
  max_query_rows: 1000
  dynamic_tools_path: .codegraph/tools.yaml

Dynamic Tools¶

Custom SQL-based tools can be defined in .codegraph/tools.yaml:

tools:
  - name: find_large_methods
    description: "Find methods with high cyclomatic complexity"
    sql: "SELECT name, Filename, CyclomaticComplexity FROM nodes_method WHERE CyclomaticComplexity > ? ORDER BY CyclomaticComplexity DESC LIMIT ?"
    parameters:
      - name: threshold
        type: integer
        description: "Minimum complexity threshold"
        default: 10
      - name: limit
        type: integer
        description: "Maximum results"
        default: 20

Only SELECT queries are allowed in dynamic tools. DDL/DML statements are rejected at load time.

Claude Code Integration¶

Add to your Claude Code MCP configuration (.claude/mcp.json):

{
  "mcpServers": {
    "codegraph": {
      "command": "python",
      "args": ["-m", "src.mcp", "--db", "data/projects/postgres.duckdb"],
      "cwd": "/path/to/codegraph"
    }
  }
}