Hosted MCP Endpoint

POST /api/v1/mcp is a hosted Model Context Protocol endpoint. It lets a remote agent use the exact same tool surface as the local stdio MCP server (npm run mcp) without running a local process — every call is a single request/response over HTTP JSON-RPC. There is no SSE / streaming; the endpoint implements the streamable-HTTP basics an agent needs: initialize, ping, tools/list, and tools/call.

POST /api/v1/mcp

Single endpoint, JSON-RPC 2.0. The HTTP method is always POST; the JSON-RPC method field selects the operation.

Authentication

Two things are required:

RBAC — the caller must resolve to role editor or admin (otherwise 403).
Credential — the request must carry either an X-API-Key header or be an internal-service call (x-user-id: system, set by middleware). A pure session cookie is rejected with 403 — this surface is for agents holding server credentials, because nested tool calls run with elevated privileges that a session role must not inherit.

X-API-Key: <your-api-key>
X-Tenant-Id: <your-tenant-id>
Content-Type: application/json

Control-plane credential required. The hosted MCP endpoint is a control-plane surface — its tools can invoke management endpoints. The API key must be minted with the control-plane scope (see API Keys). A default (data-plane-only) key gets 403 on /api/v1/mcp. Treat the key as a management credential: keep it internal and never embed it in client apps. The in-app AI assistant is unaffected — it uses a browser session, not an API key.

Tenant pinning. The authenticated tenant is forced into every tools/call — any client-supplied tenantId argument is overwritten before the tool runs. A key scoped to tenant A can never reach tenant B’s data.

Governance. The tool registry is built with governed = true. Playbook tools that would mutate data instead queue an AiRecommendation for admin / four-eyes approval rather than writing directly. See Approvals.

Rate limit

60 requests per 60 seconds per caller (fail-closed — a 429 is returned when the limiter cannot be reached).

JSON-RPC envelope

Request:

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

Successful response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": { "...": "method-specific" }
}

Error response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": { "code": -32601, "message": "Method not found: foo" }
}

Methods

initialize

Returns the server’s protocol version and capabilities.

// → result
{
  "protocolVersion": "2025-03-26",
  "capabilities": { "tools": { "listChanged": false } },
  "serverInfo": { "name": "kaireonai", "version": "1.0.0" }
}

ping

Liveness check. Returns an empty object.

// → result
{}

tools/list

Lists every registered tool with its JSON-Schema input.

// → result
{
  "tools": [
    {
      "name": "list_offers",
      "description": "List offers for the tenant",
      "inputSchema": { "type": "object", "properties": { "...": {} } }
    }
  ]
}

tools/call

Invokes a tool by name. params.name selects the tool; params.arguments carries its inputs. The authenticated tenantId is injected automatically.

// params
{
  "name": "list_offers",
  "arguments": { "limit": 10 }
}

On success the result is the tool’s own MCP content payload. A handler that throws returns a result with isError: true (not a JSON-RPC error):

// → result (handler error)
{
  "content": [{ "type": "text", "text": "{\"error\":\"...\"}" }],
  "isError": true
}

notifications/initialized is accepted and answered with 202 No Content (no body).

Tool surface

The registry reuses the same registration functions as the stdio server, grouped by module: data, studio, algorithm, operations, AI, and flow tools, plus governed playbooks. Call tools/list for the live, tenant-scoped catalog — it always reflects what the calling key can do.

Error codes

Code	Meaning	HTTP status
`-32700`	Parse error (body was not valid JSON)	`400`
`-32600`	Invalid Request (not a valid JSON-RPC 2.0 envelope)	`400`
`-32601`	Method not found	`200`
`-32602`	Invalid params (unknown tool, or arguments failed the tool’s schema)	`200`

RBAC and credential failures are returned as plain (non-JSON-RPC) 403 responses before JSON-RPC dispatch.

Example

curl -X POST https://playground.kaireonai.com/api/v1/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your-api-key>" \
  -H "X-Tenant-Id: my-tenant" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

Overview

Decisioning

Studio

Data

Algorithms & Models

Content & Metrics

Orchestration

Customers & Traces

Events & Attribution

Analytics

AI

Testing & Simulation

Export & Import

Admin

Integrations

Hosted MCP Endpoint

POST /api/v1/mcp

Authentication

Rate limit

JSON-RPC envelope

Methods

initialize

ping

tools/list

tools/call

Tool surface

Error codes

Example

​POST /api/v1/mcp

​Authentication

​Rate limit

​JSON-RPC envelope

​Methods

​initialize

​ping

​tools/list

​tools/call

​Tool surface

​Error codes

​Example

POST /api/v1/mcp

Authentication

Rate limit

JSON-RPC envelope

Methods

initialize

ping

tools/list

tools/call

Tool surface

Error codes

Example