Endpoint#
POST /api/mcp
MCP Streamable HTTP JSON-RPC transport. Accepts initialize, notifications/initialized, ping, tools/list, and tools/call. tools/call requires the mcp_access entitlement and is metered against the monthly allowance.
Authentication#
[]An empty security requirement means this operation does not declare authentication. Read operation notes for entitlement and protocol-method requirements.
Parameters#
No parameters declared by the specification.
Request body#
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"jsonrpc": {
"type": "string",
"const": "2.0"
},
"id": {
"type": [
"integer",
"string",
"null"
]
},
"method": {
"type": "string",
"enum": [
"initialize",
"ping",
"tools/list",
"tools/call"
]
},
"params": {
"type": "object"
}
}
}
}
}
}Responses and errors#
| HTTP status | Meaning |
|---|---|
| 200 | The JSON-RPC result object. |
| 202 | Accepted for a notification (no body). |
| 400 | Invalid request. JSON-RPC maps 400 to -32602. |
| 401 | Missing or invalid credential. JSON-RPC maps 401 to -32001. |
| 403 | Authenticated but not entitled. JSON-RPC maps 403 to -32003. |
| 404 | The requested resource or operation does not exist. JSON-RPC maps 404 to -32002. |
| 429 | Monthly allowance reached; no overage is charged. Retry after the calendar-month reset. Response carries RateLimit-* and X-RateLimit-* headers plus Retry-After. |
Response examples#
No response example is supplied by OpenAPI for this operation. The complete response schemas are preserved below; use an actual response for observed values.
Retry guidance#
See errors and retries. Honor operation-specific response headers. A POST may create state; do not replay it automatically.
Complete operation contract#
The expanded contract below includes all parameter constraints, response headers, schemas and examples from OpenAPI.
{
"path": "/api/mcp",
"method": "POST",
"parameters": [],
"operationId": "mcpJsonRpc",
"summary": "Send a JSON-RPC 2.0 message to the MCP endpoint",
"description": "MCP Streamable HTTP JSON-RPC transport. Accepts initialize, notifications/initialized, ping, tools/list, and tools/call. tools/call requires the mcp_access entitlement and is metered against the monthly allowance.",
"tags": [
"mcp"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"jsonrpc": {
"type": "string",
"const": "2.0"
},
"id": {
"type": [
"integer",
"string",
"null"
]
},
"method": {
"type": "string",
"enum": [
"initialize",
"ping",
"tools/list",
"tools/call"
]
},
"params": {
"type": "object"
}
}
}
}
}
},
"responses": {
"200": {
"description": "The JSON-RPC result object.",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"202": {
"description": "Accepted for a notification (no body)."
},
"400": {
"description": "Invalid request. JSON-RPC maps 400 to -32602.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "A stable machine-readable code, e.g. unauthorized or not_found."
},
"message": {
"type": "string",
"description": "A human-readable explanation."
},
"hint": {
"type": "string",
"description": "Optional resolution pointer."
}
}
}
}
}
}
}
},
"401": {
"description": "Missing or invalid credential. JSON-RPC maps 401 to -32001.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "A stable machine-readable code, e.g. unauthorized or not_found."
},
"message": {
"type": "string",
"description": "A human-readable explanation."
},
"hint": {
"type": "string",
"description": "Optional resolution pointer."
}
}
}
}
}
}
}
},
"403": {
"description": "Authenticated but not entitled. JSON-RPC maps 403 to -32003.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "A stable machine-readable code, e.g. unauthorized or not_found."
},
"message": {
"type": "string",
"description": "A human-readable explanation."
},
"hint": {
"type": "string",
"description": "Optional resolution pointer."
}
}
}
}
}
}
}
},
"404": {
"description": "The requested resource or operation does not exist. JSON-RPC maps 404 to -32002.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "A stable machine-readable code, e.g. unauthorized or not_found."
},
"message": {
"type": "string",
"description": "A human-readable explanation."
},
"hint": {
"type": "string",
"description": "Optional resolution pointer."
}
}
}
}
}
}
}
},
"429": {
"description": "Monthly allowance reached; no overage is charged. Retry after the calendar-month reset. Response carries RateLimit-* and X-RateLimit-* headers plus Retry-After.",
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
}
},
"RateLimit-Limit": {
"schema": {
"type": "integer"
}
},
"RateLimit-Remaining": {
"schema": {
"type": "integer"
}
},
"RateLimit-Reset": {
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "A stable machine-readable code, e.g. unauthorized or not_found."
},
"message": {
"type": "string",
"description": "A human-readable explanation."
},
"hint": {
"type": "string",
"description": "Optional resolution pointer."
}
}
}
}
}
}
}
}
},
"x-codeSamples": [
{
"lang": "curl",
"label": "curl (Pro key)",
"source": "curl -s 'https://china-snapshot.com/api/mcp' \\\n -H \"Authorization: Bearer $CS_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"find_records\",\"arguments\":{\"q\":\"export\",\"limit\":3}}}'"
}
]
}