# Send a JSON-RPC 2.0 message to the MCP endpoint

mcpJsonRpc · POST /api/mcp

## Endpoint
`POST /api/mcp`

MCP Streamable HTTP JSON-RPC transport. Accepts initialize, notifications/initialized, ping, tools/list, and tools/call. tools/call requires an API key (a free key or Pro) and is metered against the key's monthly allowance.

## Authentication
```json
[]
```
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
```json
{
  "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](/docs/api/overview#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.

```json
{
  "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 an API key (a free key or Pro) and is metered against the key's 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}}}'"
    }
  ]
}
```