# Katonic MCP Server

What the Katonic MCP Server is, where a client reaches it, how it authenticates, which protocol methods it answers, and how tool results and errors come back.

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](/developers/libraries/mcp-server/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.

## Related

- [Connect a client](/developers/libraries/mcp-server/connect)
- [Tools](/developers/libraries/mcp-server/tools)
- Authentication
- Public API reference
- [Connect an MCP client to the Katonic MCP Server](/tools/katonic-mcp-server) in the help centre

Source: https://docs.katonic.ai/developers/libraries/mcp-server
