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 askatonic-mcp-serverversion 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 withkapi_is answered with HTTP 401 and JSON-RPC error-32001 Unauthorizedbefore 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/callandping. 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/callreturns one text content item holding the tool's result as JSON, withisErrorfalse. When a tool fails, including when the public API refuses the call, the response is JSON-RPC error-32603with 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
waitfalse to return at once. - Health.
GET /healthanswers 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/listfrom 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.