Skip to main content

TypeScript MCP SDK

The @modelcontextprotocol/sdk package is the reference Model Context Protocol client for TypeScript and JavaScript. Its streamable HTTP transport takes your tenant's MCP endpoint and a request initialiser carrying the key; the Client then lists and calls the platform's nineteen tools from any Node program, agent framework or server-side route.

Who can use it: anyone holding an API key. Each tool needs the scope of the public API route it calls, listed on Tools.

Prerequisites​

  • Node.js 18 or later and npm install @modelcontextprotocol/sdk. Verified with 1.30.0.
  • Your tenant's MCP endpoint, https://<your tenant host>/mcp, and a key from the Developer Hub's API keys tab.
  • For the chat tool, the id of a published agent built in Studio. katonic_list_agents returns the ids.
The Connect from your client panel: the client switch with Claude Desktop, Python (MCP SDK), TypeScript (MCP SDK), OpenAI Agents and OpenCode, and the JSON snippet for Claude Desktop with the endpoint URL and a Bearer kapi_ placeholder; above it, the last rows of the built-in tool grid and the note about tools/list.The Connect from your client panel: the client switch with Claude Desktop, Python (MCP SDK), TypeScript (MCP SDK), OpenAI Agents and OpenCode, and the JSON snippet for Claude Desktop with the endpoint URL and a Bearer kapi_ placeholder; above it, the last rows of the built-in tool grid and the note about tools/list.
Connect from your client: pick the client, select Copy on its snippet and replace the kapi_ placeholder with your key.

Connect​

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
new URL("https://<your tenant host>/mcp"),
{ requestInit: { headers: { Authorization: `Bearer ${process.env.KATONIC_API_KEY}` } } },
);
const client = new Client({ name: "my-app", version: "1.0.0" });
await client.connect(transport);

console.log(client.getServerVersion()); // { name: "katonic-mcp-server", version: "2.0.0" }
const { tools } = await client.listTools();
console.log(tools.map((tool) => tool.name)); // nineteen names, katonic_chat first

The file must be a module ("type": "module" in package.json, or a .mjs extension) for the top-level await.

Call the tools​

Every tool takes an arguments object and returns content blocks; the platform's tools answer with one text block carrying JSON.

const agents = await client.callTool({ name: "katonic_list_agents", arguments: {} });
const agentId = JSON.parse(agents.content[0].text).agents[0].id;

const reply = await client.callTool({
name: "katonic_chat",
arguments: { agent_id: agentId, message: "Summarise our onboarding guide in three bullet points." },
});
const turn = JSON.parse(reply.content[0].text);
console.log(turn.message.content);
const sessionId = turn.session_id; // pass it back to continue the conversation

const hits = await client.callTool({
name: "katonic_knowledge_search",
arguments: { query: "onboarding", top_k: 5 },
});
console.log(JSON.parse(hits.content[0].text).results[0].content);

await client.close();

katonic_chat takes agent_id, message and an optional session_id; katonic_knowledge_search takes query, top_k and an optional source_ids array. A tool that fails sets isError on its result rather than throwing; a refused key surfaces as a thrown JSON-RPC error.

Verify​

  1. connect resolves and getServerVersion() names the server; listTools() returns nineteen tools. That proves the endpoint and the protocol, not the key: the server accepts the handshake from any key that starts with kapi_.
  2. The first callTool returning content proves the key and its scope. katonic_list_agents is the cheapest check.
  3. The key's row on the Developer Hub's API keys tab shows a new last-used time, and a katonic_chat or katonic_completions call appears in the Control Room's AI Gateway under Logs as a line naming the model, tier, tokens, cost and latency.

What does not carry over​

  • A server session. The server issues no session id, so each call stands alone; conversation memory belongs to the platform's sessions, addressed by the session_id the chat tool returns.
  • Streaming. Tool results arrive whole. To stream a model's tokens, call the public API's chat completions route directly with an OpenAI client.
  • Agents created through the API. An agent created with katonic_create_agent or the API's create route cannot yet hold a conversation on the current build; chat with agents published from Studio.
  • Browser use. The transport runs in a browser too, but the key would then live in the page. Keep the client server-side and let your own backend hold the key.

Troubleshooting​

  • connect rejects with a fetch error. The URL is wrong, the tenant is not licensed for the public API, or a proxy in front of you blocks the host. Confirm the address on the Developer Hub.
  • connect and listTools succeed, the first callTool throws 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 and scopes on the API keys tab.
  • katonic_chat fails on the first turn for a new agent. The agent was created through the API; publish one from Studio and use its id.
  • SyntaxError: Cannot use import statement outside a module. Add "type": "module" to package.json or rename the file to .mjs.

Describes the platform as of .

Was this page helpful?