kavilo
Sign in

Guide

Connecting your own MCP server

The agent normally answers from what you wrote in Context. When the answer is in a live system — a CRM, an inventory service, a database — you can point it at an MCP server you run instead. The agent calls that server at question time, uses what it returns, and carries on. Your source system stays in your network; the tool request and the response cross into our hosted service for that conversation.

There are two ways to do this depending on how you run kavilo:

  • Hosted Enterprise plan — configure a context provider in the portal. When a visitor's signed token carries a context key, the agent calls one MCP tool before replying so your server can return visitor-specific data. Visitors without that key skip the call.
  • Self-hosted — add one or more MCP servers to tools.mcpServers in your config.json. These become tools the agent can call during its reasoning, the same way native tools work.

Hosted Enterprise: context provider

In the portal, open your bot's settings and scroll to MCP context provider. You will set four things:

  • Endpoint URL — the HTTP or HTTPS address of your MCP server. Must be reachable from our cloud. A local address or a private IP will not work; use a public hostname or a tunnel (Cloudflare Tunnel, Tailscale Funnel, ngrok) during development.
  • Tool name — the name of the MCP tool to call. This is the tool your server exposes; the name is yours to choose.
  • Header carrying the visitor key (optional) — the header name used to forward the opaque context key from your backend-minted visitor token. It defaults to X-Context-Key. The tool is called only when that token contains a key; public-key visitors skip the call.
  • Auth header and credential (optional) — a header and static value that identifies kavilo to your server, for example X-API-Key and a secret you mint. Separate from the context key: the auth credential identifies the caller, the context key identifies the visitor. The credential is write-only — you set it and we never return it.

After saving, use Test connection to verify the agent can reach your server and call the tool. The test lists the tools your server exposes; if the named tool is not in that list, it will not be available to the bot at runtime.

At runtime, a visitor carrying a context key triggers the tool before the reply. What it returns is injected into the agent's context for that turn. If the call times out (default five seconds) or returns an error, the agent continues without it rather than refusing to reply — design your tool to return quickly and degrade gracefully.

The raw tool response is not added to the bot's permanent Context, but facts from it may appear in the reply and therefore in the stored conversation and transcript.

Self-hosted: tools.mcpServers

In config.json, add each server under tools.mcpServers. The key is the alias; the agent sees tools named mcp_<alias>_<tool>.

An HTTP server:

"tools": { "mcpServers": { "inventory": { "url": "https://internal.example.com/mcp", "enabled": true } } }

A local process (stdio):

"tools": { "mcpServers": { "crm": { "command": "npx", "args": ["-y", "@example/crm-mcp"], "env": { "CRM_API_KEY": "sk_…" }, "enabled": true } } }

The agent calls these tools on its own initiative during reasoning, the same way it calls built-in tools. You can also set enabledTools to restrict which tools from a server are exposed.

Changes to config.json take effect on the next kavilo start. The kavilo mcp command helps manage server entries without hand-editing the file.

What leaves your network

On the hosted Enterprise plan, the conversation, MCP request and tool response are processed in our cloud. Your underlying system stays in your network, but the request, optional signed visitor token and returned rows or objects cross the boundary. If that is not acceptable, self-host the agent and use local inference so neither the conversation nor tool data leaves.

Getting access

MCP context is available on the Enterprise plan. On lower plans the settings are hidden. Upgrade or talk to us if you want to discuss the data boundary before choosing a deployment.