Connecting MCP servers

An MCP server publishes a set of tools in a standard way. Connect one and your AI chatbot can use its tools in a conversation, next to the HTTP tools you define yourself. Many products already offer an MCP server (order systems, calendars, CRMs), so you can often add actions without writing any API glue.

Looking for the other direction, letting Claude or Cursor manage your Kerabie account? See the Kerabie MCP server.

Connect a server

1. Open AI Tools in the dashboard and choose Add MCP server.
2. Enter a name, a description, and the server's URL (its Streamable HTTP endpoint), plus any authentication it needs: a bearer token, or an API key sent in a header you choose.
3. Kerabie connects, reads the tools the server offers, and lists them. None are switched on yet.
4. Switch on the tools you want the chatbot to use, and use Test to run one before the AI does.
5. For each switched-on tool, choose its route: Public or Secure. Kerabie suggests one; see Public and secure tools.

When the server adds, renames or removes tools, press Sync. Tools you had switched on that the server no longer offers are dropped.

Public and secure tools

The AI agent in your app can use your tools as the signed-in customer. Every tool has a route:

• Public tools need no customer, for example searching products. If the server marks a tool read-only (the MCP readOnlyHint annotation), repeat answers are cached for 30 seconds.
• Secure tools act for one customer: cart, orders, saved addresses, pickups, payments, anything that changes something. Kerabie sends the customer's token in the X-Kerabie-User-Token header, keeps it encrypted for the length of the call and never shows it to the AI. Secure tools are only offered while someone is signed in, and are not used by the website chat or by calls from visitors who are not signed in.

When you connect a server, tools that change something, and tools about the customer's own data, start as Secure. Review them before you switch tools on. After a Sync, tools you already chose keep their route and new tools get a suggestion.

Write a good description

The description is how the chatbot tells your servers apart. It is shown to the AI with every tool the server offers, so say what the server is for and when to use it:

Order and stock lookups for our online shop. Use when a customer asks where their order is or whether an item is available.

It must be 10 to 300 characters. If you connect several servers, make each description say clearly what the others don't cover, so the AI doesn't pick the wrong one.

How the chatbot uses them

• The chatbot sees each switched-on tool's name and description, led by your server's name and description, and decides when to call it, exactly as with your own tools.
• Inputs that are objects or arrays are asked for as JSON and converted back before the call.
• A tool's text answer is shown to the AI (cut at 8,000 characters). If the tool reports an error or the server is slow to answer (10 seconds), the AI is told the request failed.
• Every call is made fresh: Kerabie connects, calls the tool and disconnects.

Limits and safety

• Plan limit. Every switched-on MCP tool counts towards your plan's AI tool limit, together with your own tools. If you downgrade, the chatbot keeps using your own tools first, then MCP tools, up to the new limit.
• Up to 5 servers per organisation, and up to 100 tools read from each.
• Public addresses only. Servers on localhost, private networks or cloud metadata addresses are rejected, and redirects are not followed.
• Secrets are write-only. Tokens and API-key values are never shown again after you save them. Leave the field blank when editing to keep the stored one.
• Trust. The chatbot will call whatever you switch on, with details a customer gives it. Only connect servers you trust, and switch on the tools you actually want.

From code

const { server } = await kerabie.mcpServers.create({
  name: 'Shop tools',
  description: 'Order and stock lookups for our shop. Use when a customer asks about an order or an item.',
  url: 'https://mcp.yourstore.com/mcp',
  authType: 'bearer',
  authConfig: { token: process.env.SHOP_MCP_TOKEN },
});

await kerabie.mcpServers.update(server.id, { enabledTools: ['check_stock'] });
await kerabie.mcpServers.test(server.id, 'check_stock', { sku: 'A-100' });