# TypeScript MCP SDK

Connect the official @modelcontextprotocol/sdk client to your tenant's MCP server from Node or the browser, list the tools, call one and read the JSON it returns.

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](/developers/libraries/mcp-server/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.](https://docs.katonic.ai/img/developers/libraries/mcp-server/connect/dev-hub-mcp-connect.png)
*Connect from your client: pick the client, select Copy on its snippet and replace the kapi_ placeholder with your key.*

## Connect

```typescript

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.

```typescript
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`.

## Related

- [Katonic MCP Server](/developers/libraries/mcp-server)
- [Tools](/developers/libraries/mcp-server/tools)
- [Python MCP SDK](/developers/integrations/mcp-python-sdk)
- [Integrations](/developers/integrations/overview)

Source: https://docs.katonic.ai/developers/integrations/mcp-typescript-sdk
