---
title: "MCP JSON-RPC request"
method: POST
path: "/mcp/messages"
tags: ["MCP"]
---

# MCP JSON-RPC request

`POST /mcp/messages`

## Request

- Base URL: `https://api.johnsessentials.com`
- URL: `https://api.johnsessentials.com/mcp/messages`
- Auth: HTTP bearer

Synchronous JSON-RPC 2.0 request. Common methods:

- `initialize` — handshake. Returns server capabilities.
- `notifications/initialized` — client signals it's ready.
- `tools/list` — list every callable tool (≥30 free; the full catalogue on paid plans).
- `tools/call` — execute a tool with arguments.
- `resources/list` — list `memory://files`, `memory://anchors`, `workflows://saved`.
- `resources/read` — read a resource by URI.
- `prompts/list` — list the 6 demo prompts.
- `prompts/get` — render a prompt with arguments.

See [MCP spec 2025-03-26](https://modelcontextprotocol.io/specification)
for the full method catalog.

## Headers

- `Mcp-Session-Id` string

## Request body

- JSONRPCRequest
  - `id` union: Request ID. Omit for notifications (the server won't reply).
    - string
    - integer
  - `jsonrpc` '2.0', required
  - `method` string, required: One of: `initialize`, `notifications/initialized`, `tools/list`, `tools/call`, `resources/list`, `resources/read`, `prompts/list`, `prompts/get`, `ping`.
  - `params` object: Method-specific parameters.

## Response `200`

JSON-RPC response.

- JSONRPCResponse
  - `error` JSONRPCError
    - `code` integer, required: Standard JSON-RPC error codes (-32700 parse error, -32600 invalid request, -32601 method not found, -32602 invalid params, -32603 internal error). MCP additionally uses -32001 (CodeNotImplemented), -32002 (lifecycle not ready).
    - `data` unknown
    - `message` string, required
  - `id` union, required
    - string
    - integer
  - `jsonrpc` '2.0', required
  - `result` unknown

## Other responses

- `401`: Auth failed (missing/malformed/invalid/expired/inactive key).
- `402`: Monthly USD cost cap reached for this key (quota_cost_exceeded). Phase 3 / M3.
- `429`: Sliding 1-hour rate limit exceeded.

---

[API](https://skmtc.dev/johnsessentials/apis/john-s-essentials-api.md) · [All operations](https://skmtc.dev/johnsessentials/apis/john-s-essentials-api/llms.txt) · [OpenAPI document](https://skmtc.dev/johnsessentials/apis/john-s-essentials-api/revisions/56586ff78e6d?raw)