# Endpoints (/aiway/mcp/reference/endpoints)



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](/connectors/concepts/shared-http-server#enable-model-on-by-default) for the enable model and the irregular var name).

## HTTP endpoints [#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 [#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](/aiway/mcp/reference/tools-reference). For the JSON-RPC and tool-level error model, see [Error codes](/aiway/mcp/reference/error-codes).

## Headers [#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](/aiway/mcp/guides/authentication).                                         |

## Request shape [#request-shape]

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

```json
{
  "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 [#notification-shape]

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

```json
{
  "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 [#initialize-response]

```json
{
  "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](/aiway/mcp/guides/session-management) for the full lifecycle.

## HTTP status codes [#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](/aiway/mcp/reference/error-codes). |

## Endpoint signatures [#endpoint-signatures]

The following `curl` calls cover every method on the endpoint.

<Tabs groupId="language" items="['curl']">
  <Tab value="curl">
    ```bash
    # 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>"
    ```
  </Tab>
</Tabs>

## Related [#related]

<Cards>
  <Card title="Tools reference" href="/aiway/mcp/reference/tools-reference" description="The full 15-tool catalog: arguments, defaults, and response shapes." />

  <Card title="Error codes" href="/aiway/mcp/reference/error-codes" description="JSON-RPC base codes, the -32010 auth code, and isError tool semantics." />

  <Card title="Session management" href="/aiway/mcp/guides/session-management" description="The initialize handshake, MCP-Session-Id, batching, and keepalive." />

  <Card title="Getting started" href="/aiway/mcp/getting-started" description="Run the handshake and your first tool call end-to-end." />
</Cards>