Protocol Specification v2024-11-05
MCP API & JSON-RPC Reference
The BotDigit MCP server implements the official Model Context Protocol over JSON-RPC 2.0. This page documents the low-level wire format, standard methods, and error response structures.
1. Initialization Handshake (`initialize`)
Before calling any tools, the client negotiates capabilities and protocol versions by sending an initialize request:
Request Payload:
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"capabilities": {
"roots": { "listChanged": true },
"sampling": {}
},
"clientInfo": {
"name": "cursor",
"version": "0.42.0"
}
}
}Successful Response:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"protocolVersion": "2024-11-05",
"capabilities": {
"tools": { "listChanged": false },
"resources": { "subscribe": true, "listChanged": true },
"prompts": { "listChanged": false }
},
"serverInfo": {
"name": "botdigit-mcp-gateway",
"version": "1.4.0"
}
}
}2. Tool Invocation (`tools/call`)
Clients execute operations by sending tools/call with the tool name and validated arguments:
Request Example (Linking Git Commit):
{
"jsonrpc": "2.0",
"id": 42,
"method": "tools/call",
"params": {
"name": "link_git_commit",
"arguments": {
"task_id": "tsk_8819_stripe",
"commit_sha": "a1b2c3d4e5f67890123456789abcdef012345678",
"commit_message": "fix(checkout): add idempotent key header to charge requests"
}
}
}Response Payload:
{
"jsonrpc": "2.0",
"id": 42,
"result": {
"content": [
{
"type": "text",
"text": "{\"status\":\"success\",\"commit_sha\":\"a1b2c3d4e5f67890123456789abcdef012345678\",\"evidence_id\":\"ev_9921_link\"}"
}
],
"isError": false
}
}3. Standard & BotDigit Error Codes
| Code | Error Name | Description & Cause |
|---|---|---|
| -32700 | Parse error | Invalid JSON was received by the server while parsing the body. |
| -32600 | Invalid Request | The JSON sent is not a valid JSON-RPC 2.0 Request object. |
| -32601 | Method not found | The requested method does not exist or is not available on this server. |
| -32602 | Invalid params | Invalid method parameters that violate the tool’s published JSON Schema. |
| -32603 | Internal error | Internal JSON-RPC error occurred within the BotDigit MCP gateway. |
| -32001 | Unauthorized / Scope Required | The provided PAT is invalid, expired, or lacks the necessary permission scope for the tool. |
| -32002 | Approval Required | Operation staged. Action cannot execute autonomously without explicit human authorization. |
| -32003 | Rate Limit Exceeded | Exceeded maximum allowable requests per minute for the authenticated developer token. |
| -32004 | Workspace Isolation Error | Target resource does not belong to an authorized workspace or tenancy boundary. |
Example: Staged Financial Approval Response (-32002)
When an AI agent calls prepare_payment_release, the operation is paused and returns a human approval URL:
{
"jsonrpc": "2.0",
"id": 103,
"result": {
"content": [
{
"type": "text",
"text": "{\"staged\":true,\"action\":\"payment_release\",\"amount_usd\":2500,\"approval_url\":\"https://botdigit.com/approvals/payment/tok_sec_9921_alpha\",\"expires_in_minutes\":15}"
}
]
}
}Setup Cursor IDE with BotDigit
Configure your .cursor/mcp.json file in 60 seconds.