Skip to main content

Katonic MCP Server

Public API

The Katonic MCP Server exposes the platform to any client that speaks the Model Context Protocol: Claude Desktop, Cursor, the MCP SDKs, OpenAI Agents, OpenCode or an agent you write yourself. It runs inside your tenant at https://<your tenant host>/mcp, the address shown as MCP in the header of Studio's Developer Hub. A client connects with an API key, lists the tools and calls them; every tool call becomes a public API request made with that key, so the key's scopes decide what the client may do.

Who can use it: anyone holding an API key for a tenant licensed for the public API. Keys are created on the API keys tab of the Developer Hub; see Authentication.

How it works​

  • Transport. Streamable HTTP: the client posts JSON-RPC 2.0 messages to /mcp. The server implements protocol version 2025-03-26 and identifies itself as katonic-mcp-server version 2.0.0 in the initialize handshake. A request array is handled as a batch and answered with an array.
  • Authentication. Every request carries Authorization: Bearer kapi_.... A request whose token does not start with kapi_ is answered with HTTP 401 and JSON-RPC error -32001 Unauthorized before anything else happens. The key's validity, scopes and rate limits are checked by the public API gateway when a tool runs, so a revoked or under-scoped key connects and lists tools but fails on the call.
  • Methods. initialize, tools/list, tools/call and ping. The server declares the tools capability only; it serves no resources and no prompts. Any other method returns -32601 Method not found.
  • Tool results. A successful tools/call returns one text content item holding the tool's result as JSON, with isError false. When a tool fails, including when the public API refuses the call, the response is JSON-RPC error -32603 with the failure as its message. A call without a tool name returns -32602 Missing tool name; a body that is not JSON returns HTTP 400 and -32700 Parse error.
  • Long-running tools. Running an evaluation and optimising a prompt wait for the job by default and return the finished record, or a timeout error carrying the run or job id so you can poll the public API yourself. Pass wait false to return at once.
  • Health. GET /health answers without a key with the service name and its tool count.

What the tools cover​

The server ships 19 tools: chat with an agent, OpenAI-compatible completions, knowledge search, document ingest and data analysis; listing, creating and updating agents; sessions and their history; datasets and evaluation runs; prompt optimisation; the data flywheel's quality trend; knowledge sources; searching the governed tool catalog and executing a tool; usage and cost analytics; and feedback. Each tool, its parameters and the public API routes it calls are listed on Tools.

Limits and behaviour​

  • The tool list is the built-in catalog of the server build your tenant runs. The Developer Hub's grid shows the catalog for the current build; tools/list from your client is the authoritative list for your deployment.
  • The server does not validate arguments against a tool's schema before running it. A missing required argument fails inside the tool with the tool's own message.
  • Because every tool call goes through the public API gateway, the key's per-minute and per-day limits apply to tool calls as they do to direct calls, and the gateway's error codes arrive inside the tool error's message.
  • One tool on the current build sends its source filter under a name the search route does not read, so knowledge search is not limited to the sources named; the tool's entry says so.

Describes the platform as of .

Was this page helpful?