MCP Endpoint Reference

The Ithil Gateway exposes a small HTTP surface conforming to MCP 2024-11-05 . These endpoints are consumed by MCP-compatible AI agents.

POST /mcp

JSON-RPC 2.0 dispatch endpoint. Requires a valid Bearer JWT in the Authorization header.

Authorization: Bearer <agent-jwt>

Responses are streamed as Server-Sent Events :

event: message
data: {"jsonrpc":"2.0","id":1,"result":{...}}

Session lifecycle

Every agent must initialize a session before making tool calls. The gateway returns an Mcp-Session-Id header on the initialize response; include it in all subsequent requests.

Supported methods

initialize

Opens an MCP session. Call this once before any tool calls.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "my-agent", "version": "1.0.0" }
  }
}

Copy the Mcp-Session-Id value from the response headers and include it as a header on all subsequent requests.

tools/list

Returns the tools the authenticated agent is permitted to call.

{ "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {} }

tools/call

Calls a single tool.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "GetOrderStatus",
    "arguments": { "id": "ORD-12345" }
  }
}

Response (SSE):

event: message
data: {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"{\"orderId\":\"ORD-12345\",\"status\":\"Shipped\"}"}]}}

Error codes

GET /health/live

Always returns 200 OK if the gateway process is running. Use for container liveness probes.

GET /health/ready

Returns 200 OK when Redis and the ONNX embedding model are ready. Use for load balancer readiness gates — never route agent traffic until this endpoint is healthy.

Response:

{
  "status": "Healthy",
  "components": {
    "redis": { "status": "Healthy" },
    "onnxModel": { "status": "Healthy" }
  }
}

When unhealthy:

{
  "status": "Unhealthy",
  "components": {
    "redis": { "status": "Unhealthy", "description": "Connection refused" },
    "onnxModel": { "status": "Healthy" }
  }
}