---
updatedAt: 2026-05-22T16:57:28.000Z
agentTools:
  projectIndex: https://docs.oneschema.co/llms.txt
---

# Send an MCP JSON-RPC request

Send a JSON-RPC 2.0 request to the OneSchema MCP server. MCP clients use
this endpoint to initialize the connection, list available tools and
resources, call read-only tools, and read resources.

Notifications that do not require a response return `202 Accepted` with
an empty body. Requests return a JSON-RPC response object.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "MCP Server",
    "version": "1",
    "contact": {
      "name": "OneSchema Support",
      "email": "support@oneschema.co"
    },
    "license": {
      "name": "proprietary",
      "url": "https://www.oneschema.co/terms-and-conditions"
    },
    "termsOfService": "https://www.oneschema.co/terms-and-conditions",
    "description": "OneSchema's MCP (Model Context Protocol) server exposes read-only access to\nOneSchema API specifications and product guides for AI coding assistants.\n\nThe endpoint uses JSON-RPC 2.0 over Streamable HTTP transport. Configure\nyour MCP client to use `https://api.oneschema.co/mcp` with your existing\nOneSchema API key in the `X-API-KEY` header."
  },
  "tags": [
    {
      "name": "MCP Server",
      "description": "Read-only MCP operations for API specs and product guides"
    }
  ],
  "paths": {
    "/mcp": {
      "post": {
        "operationId": "send-mcp-json-rpc",
        "summary": "Send an MCP JSON-RPC request",
        "description": "Send a JSON-RPC 2.0 request to the OneSchema MCP server. MCP clients use\nthis endpoint to initialize the connection, list available tools and\nresources, call read-only tools, and read resources.\n\nNotifications that do not require a response return `202 Accepted` with\nan empty body. Requests return a JSON-RPC response object.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "JSON-RPC response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcResponse"
                },
                "examples": {
                  "JSON-RPC error": {
                    "summary": "JSON-RPC error",
                    "value": {
                      "jsonrpc": "2.0",
                      "id": 3,
                      "error": {
                        "code": -32602,
                        "message": "Invalid params",
                        "data": "No tool found: unknown_tool"
                      }
                    }
                  },
                  "Get an API spec with a tool call": {
                    "summary": "Get an API spec with a tool call",
                    "value": {
                      "jsonrpc": "2.0",
                      "id": 3,
                      "result": {
                        "content": [
                          {
                            "type": "text",
                            "text": "{\"api_group\":\"importer\",\"endpoint_count\":20,\"spec\":\"openapi: 3.1.0\\n...\"}"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "Notification accepted; no response body"
          },
          "401": {
            "description": "Unauthorized (missing or invalid API key)"
          },
          "403": {
            "description": "Forbidden"
          },
          "422": {
            "description": "Request could not be processed"
          }
        },
        "tags": [
          "MCP Server"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonRpcRequest"
              },
              "examples": {
                "Read an API spec resource": {
                  "summary": "Read an API spec resource",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 4,
                    "method": "resources/read",
                    "params": {
                      "uri": "oneschema://api/importer"
                    }
                  }
                },
                "Get an API spec with a tool call": {
                  "summary": "Get an API spec with a tool call",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 3,
                    "method": "tools/call",
                    "params": {
                      "name": "get_api_spec",
                      "arguments": {
                        "api_group": "importer"
                      }
                    }
                  }
                },
                "List available tools": {
                  "summary": "List available tools",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 2,
                    "method": "tools/list"
                  }
                },
                "Initialize the MCP server": {
                  "summary": "Initialize the MCP server",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 1,
                    "method": "initialize",
                    "params": {
                      "protocolVersion": "2024-11-05",
                      "capabilities": {},
                      "clientInfo": {
                        "name": "example-client",
                        "version": "1.0.0"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "components": {
    "schemas": {
      "JsonRpcError": {
        "type": "object",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "integer"
          },
          "message": {
            "type": "string"
          },
          "data": {
            "description": "Optional method-specific error details."
          }
        },
        "additionalProperties": false
      },
      "JsonRpcParams": {
        "type": "object",
        "unevaluatedProperties": {}
      },
      "JsonRpcRequest": {
        "type": "object",
        "required": [
          "jsonrpc",
          "method"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "enum": [
              "2.0"
            ],
            "description": "JSON-RPC protocol version"
          },
          "id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Request identifier. Omit for notifications."
          },
          "method": {
            "type": "string",
            "description": "JSON-RPC method, such as `initialize`, `tools/list`, `tools/call`, `resources/list`, or `resources/read`."
          },
          "params": {
            "allOf": [
              {
                "$ref": "#/components/schemas/JsonRpcParams"
              }
            ],
            "description": "Method-specific parameters."
          }
        },
        "additionalProperties": false
      },
      "JsonRpcResponse": {
        "type": "object",
        "required": [
          "jsonrpc"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "enum": [
              "2.0"
            ]
          },
          "id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "The request identifier."
          },
          "result": {
            "allOf": [
              {
                "$ref": "#/components/schemas/JsonRpcResult"
              }
            ],
            "description": "Present for successful JSON-RPC requests."
          },
          "error": {
            "$ref": "#/components/schemas/JsonRpcError"
          }
        },
        "additionalProperties": false
      },
      "JsonRpcResult": {
        "type": "object",
        "unevaluatedProperties": {}
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-KEY"
      }
    }
  },
  "servers": [
    {
      "url": "https://api.oneschema.co",
      "description": "Production server (hosted in the US)",
      "variables": {}
    },
    {
      "url": "https://api.eu.oneschema.co",
      "description": "Production server (hosted in the EU)",
      "variables": {}
    },
    {
      "url": "https://api.ca.oneschema.co",
      "description": "Production server (hosted in Canada)",
      "variables": {}
    },
    {
      "url": "https://api.au.oneschema.co",
      "description": "Production server (hosted in Australia)",
      "variables": {}
    }
  ],
  "x-readme": {
    "explorer-enabled": false,
    "proxy-enabled": false
  }
}
```