The MCP connector exposes a single HTTP path, /mcp, on the shared HTTP server (port 9090). All tool discovery and invocation flow through it as JSON-RPC 2.0 over the Streamable HTTP transport.

The connector is enabled by default — start kubemq-server and /mcp is live; no =true flag is needed. To disable it, set CONNECTORSMCP_ENABLE=false (see Shared HTTP server for the enable model and the irregular var name).

HTTP endpoints

Method	Path	Description
`POST`	`/mcp`	JSON-RPC 2.0 request handler — a single request or a JSON array (batch). Carries `initialize`, `ping`, `tools/list`, `tools/call`, and notifications.
`GET`	`/mcp`	SSE keepalive stream. Holds an event-stream connection open; clients that prefer a long-lived channel use it alongside the stateless `POST`.

Both routes pass through origin validation; POST /mcp additionally runs the per-route timeout middleware.

JSON-RPC methods

POST /mcp accepts the following methods:

Method	Type	Description
`initialize`	Request	Start a session and negotiate capabilities. Returns `protocolVersion`, `capabilities`, `serverInfo`, and `_meta.sessionId`.
`notifications/initialized`	Notification	Client confirms initialization is complete. No `id` field; the server replies `200 OK` with body `{"jsonrpc":"2.0","result":null,"id":null}`.
`ping`	Request	Health check. Returns an empty result `{}`.
`tools/list`	Request	Discover the available tools with their `inputSchema` (11 core tools, plus 4 agent-bridge tools when the agent registry is available).
`tools/call`	Request	Invoke a tool by name with its `arguments`.

The full tool catalog and per-tool arguments live in Tools reference. For the JSON-RPC and tool-level error model, see Error codes.

Headers

Header	Direction	Description
`Content-Type`	Request	Must be `application/json`.
`MCP-Session-Id`	Both	Session identifier. The server sets it in the `initialize` response (`_meta.sessionId`); the client echoes it on every subsequent request.
`MCP-Protocol-Version`	Response	Negotiated protocol version — always `2025-11-25`.
`Authorization`	Request	`Bearer <token>` when JWT auth is enabled. See Authentication.

Request shape

A JSON-RPC 2.0 request carries an id so the client can correlate the response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "<method_name>",
  "params": { }
}

jsonrpc — must be "2.0".
id — request identifier; the response echoes this value.
method — one of the JSON-RPC methods above.
params — method-specific parameters (object). Optional when the method takes no arguments, such as ping.

Notification shape

Notifications omit the id field. The server processes them but returns no JSON-RPC result body:

{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}

In a batch (POST with a JSON array), notification entries are executed but produce no response entry.

initialize response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-11-25",
    "capabilities": {
      "tools": { "listChanged": false },
      "resources": null,
      "prompts": null
    },
    "serverInfo": {
      "name": "kubemq",
      "version": "<server version>"
    },
    "_meta": {
      "sessionId": "<uuid>"
    }
  }
}

Save result._meta.sessionId and send it back as the MCP-Session-Id header on every later request. See Session management for the full lifecycle.

HTTP status codes

Status	Meaning
`200`	Success — covers successful results, notifications (body `{"jsonrpc":"2.0","result":null,"id":null}`), and JSON-RPC error responses. A protocol error — including an auth failure (code `-32010`) — still returns `200` with an `error` object in the body, never `401`. See Error codes.

Endpoint signatures

The following curl calls cover every method on the endpoint.

# initialize — start a session, capture _meta.sessionId
curl -X POST http://localhost:9090/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-25",
      "capabilities": {},
      "clientInfo": { "name": "curl", "version": "1.0.0" }
    }
  }'

# notifications/initialized — confirm; server replies 200 with {"jsonrpc":"2.0","result":null,"id":null}
curl -X POST http://localhost:9090/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Session-Id: <session-id>" \
  -d '{
    "jsonrpc": "2.0",
    "method": "notifications/initialized"
  }'

# ping — health check, returns an empty result {}
curl -X POST http://localhost:9090/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Session-Id: <session-id>" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "ping" }'

# tools/list — discover tools and their inputSchema
curl -X POST http://localhost:9090/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Session-Id: <session-id>" \
  -d '{ "jsonrpc": "2.0", "id": 3, "method": "tools/list" }'

# tools/call — invoke a tool by name
curl -X POST http://localhost:9090/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Session-Id: <session-id>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "queue_send",
      "arguments": { "channel": "my-queue", "body": "Hello from MCP" }
    }
  }'

# GET /mcp — open the SSE keepalive stream
curl -N http://localhost:9090/mcp \
  -H "Accept: text/event-stream" \
  -H "MCP-Session-Id: <session-id>"

Endpoints

HTTP endpoints

JSON-RPC methods

Headers

Request shape

Notification shape

initialize response

HTTP status codes

Endpoint signatures

Tools reference

Error codes

Session management

Getting started

On this page