Skip to main content

Claude Code

Claude Code speaks the Model Context Protocol, and your tenant's MCP server speaks it back over streamable HTTP. One command registers the server with the key in a header; from then on Claude Code can list your agents, chat with a published agent, search your knowledge, run evaluations and call governed tools, each as an MCP tool it decides to use.

Who can use it: anyone holding an API key. Each tool needs the scope of the public API route it calls, listed on Tools; the Full access preset covers all of them, Coding agent (OpenCode) covers chat, search and completions.

Prerequisites​

  • Claude Code 2.1 or later. Verified with 2.1.79.
  • Your tenant's MCP endpoint, https://<your tenant host>/mcp. The MCP server tab of Studio's Developer Hub has a Copy URL button.
  • A key. Create it on the API keys tab of the same page; the value is shown once.
  • At least one published agent, built in Studio, if you want the chat tool to answer. An agent created through the API's own create route cannot yet hold a conversation on the current build.
The Developer Hub with the MCP server tab selected: the header chips for the API and MCP addresses with Copy, the six tabs, the MCP server endpoint banner with Copy URL and the Transport and Auth line, the Available tools grid of nineteen built-in tools with a note that tools/list is the authoritative list, the Connect from your client switch, and the top of the Claude Desktop JSON snippet.The Developer Hub with the MCP server tab selected: the header chips for the API and MCP addresses with Copy, the six tabs, the MCP server endpoint banner with Copy URL and the Transport and Auth line, the Available tools grid of nineteen built-in tools with a note that tools/list is the authoritative list, the Connect from your client switch, and the top of the Claude Desktop JSON snippet.
The MCP server tab: copy the endpoint, read the built-in tool catalog and pick your client under Connect from your client. The grid shows the catalog for the current server build; tools/list from your client is the authoritative list for your deployment.

Connect​

Register the server. The default scope is the current folder; add --scope user to make it available in every folder.

claude mcp add --transport http katonic https://<your tenant host>/mcp \
--header "Authorization: Bearer kapi_YOUR_KEY"

For a team folder, --scope project writes a .mcp.json that is meant to be committed. Keep the key out of it with Claude Code's environment-variable expansion:

{
"mcpServers": {
"katonic": {
"type": "http",
"url": "https://<your tenant host>/mcp",
"headers": { "Authorization": "Bearer ${KATONIC_API_KEY}" }
}
}
}

Then set KATONIC_API_KEY in the shell that starts Claude Code.

Verify​

  1. The handshake. claude mcp list performs it and reports one line per server:

    katonic: https://<your tenant host>/mcp (HTTP) - ✓ Connected

    Connected means the protocol handshake succeeded. It does not prove the key: the server accepts the handshake from any key that starts with kapi_ and refuses only the first tool call.

  2. The tools. Inside a Claude Code session, /mcp lists the server and its nineteen tools, named mcp__katonic__katonic_list_agents and so on.

  3. A first call. Ask Claude Code to list your Katonic agents. It calls katonic_list_agents and reads back the published agents of your tenant. Then ask it to send a message to one of them by name; it calls katonic_chat with the agent's id and shows the reply.

  4. The record. The key's row on the Developer Hub's API keys tab shows a new last-used time. A chat or completion tool call also appears in the Control Room's AI Gateway under Logs as a line naming the model, tier, tokens, cost and latency.

To remove the server later:

claude mcp remove katonic

What does not carry over​

  • Claude Code's own model. Claude Code keeps reasoning with Anthropic's models on Anthropic's terms. Nothing it says to you goes through your tenant's AI Gateway; only the tool calls do, and only katonic_chat and katonic_completions reach a model on your side.
  • Sign-in. There is no OAuth on the MCP endpoint on the current build; the key in the header is the whole of authentication.
  • A server session. The server issues no session id, so each tool call stands alone. Conversation memory belongs to the platform's sessions: pass the session_id that katonic_chat returns back into the next call to continue a conversation.
  • Governance travels with the key. The tools can only reach routes the key's scopes allow, and the key's own rate limits apply to every call, whichever client made it.

Troubleshooting​

  • claude mcp list shows the server as failed. The URL is wrong, the tenant is not licensed for the public API, or the network in front of you blocks the host. Confirm the address on the Developer Hub and that curl https://<your tenant host>/mcp returns an HTTP status rather than a connection error.
  • Connected, but the first tool call fails with an internal error. The key is invalid, expired, revoked, or lacks the tool's scope; the server reports all four the same way on the current build. Check the key's row on the API keys tab and its scopes.
  • katonic_chat returns an error on the first turn for a new agent. The agent was created through the API's create route rather than in Studio. Publish an agent from Studio and use its id.
  • The tools are missing from /mcp after a --scope project add. Claude Code asks once whether to trust a project's .mcp.json; answer yes, or re-add with the default scope.

Describes the platform as of .

Was this page helpful?