Kolio MCP server and external MCP sources

11.1Which two MCP directions does Kolio support?

MCP (Model Context Protocol) is an open protocol (specification at modelcontextprotocol.io) in which an AI client receives a list of tools with input schemas from a server and calls them over JSON-RPC 2.0; Kolio uses it as a server (your data for external agents) and as a client (your systems' data for the Kolio agent).

You manage both directions on one page, Settings → MCP sources and integrations. The upper section Kolio as a source for external systems holds the MCP server URL, API keys and webhooks; the lower section External sources inside Kolio holds the Add server form and the list of connected sources.

11.2How do I connect Claude or another client to the Kolio MCP server?

The Kolio MCP server lives at https://kolio.si/api/mcp; a client needs this URL and an Authorization: Bearer kolio_sk_… header with an API key created in Kolio — any client that supports remote MCP servers over Streamable HTTP connects without extra software.

claude mcp add --transport http kolio \
  https://kolio.si/api/mcp \
  --header "Authorization: Bearer kolio_sk_…"

{
  "mcpServers": {
    "kolio": {
      "type": "http",
      "url": "https://kolio.si/api/mcp",
      "headers": {
        "Authorization": "Bearer kolio_sk_…"
      }
    }
  }
}

11.3Which tools does the Kolio MCP server offer?

The Kolio MCP server offers 21 tools — 9 for the calendar and 12 for the CRM — and each requires exactly one key scope; tools/list returns only the tools the key has a scope for, so a client never sees a tool that would be refused.

On initialize the server sends the client a short instruction: look data up first (list_events, find_free_slots, list_contacts, list_tasks) and only then create or change, to avoid duplicate contacts or overlapping bookings. Ids returned by read tools are the input for write tools. Write tools fire the same webhooks as REST (booking.created, booking.cancelled, contact.created, task.created, task.updated).

11.4Example call: JSON-RPC over curl

The Kolio MCP server uses the stateless Streamable HTTP transport: each call is one POST to https://kolio.si/api/mcp with a JSON-RPC 2.0 body and one JSON response; the protocol version is 2025-06-18, the server name kolio, and the supported methods are initialize, ping, tools/list and tools/call.

curl -s https://kolio.si/api/mcp \
  -H "Authorization: Bearer kolio_sk_…" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# response (abridged)
{ "jsonrpc": "2.0", "id": 1,
  "result": { "tools": [
    { "name": "list_events", "description": "Vrne termine …", "inputSchema": { "type": "object", "…": "…" } },
    { "name": "find_free_slots", "…": "…" }
  ] } }

curl -s https://kolio.si/api/mcp \
  -H "Authorization: Bearer kolio_sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "find_free_slots",
      "arguments": { "service_id": "<service id>", "date_from": "2026-09-21", "date_to": "2026-09-25" }
    }
  }'

# response
{ "jsonrpc": "2.0", "id": 2,
  "result": { "content": [ { "type": "text", "text": "Prosti termini …" } ] } }

# business error (a successful JSON-RPC response the agent can correct)
{ "jsonrpc": "2.0", "id": 2,
  "result": { "isError": true, "content": [ { "type": "text", "text": "Termin je že zaseden." } ] } }

11.5How do I connect my own system as an MCP source in Kolio?

You add an external MCP source in the External sources inside Kolio section of Settings → MCP sources and integrations; a source needs a name, an https:// address of a Streamable HTTP endpoint and, if required, a credential — after adding it you discover its tools with Test connection and enable each tool individually.

11.6Tool policy and the allowed-tools list

Writing to your system requires two deliberate decisions: the Also allow changing data policy on the source and enabling the specific write tool in the allowed-tools list; the default policy is Read only, the allowed-tools list is empty when a source is added, and a refresh never widens it on its own.

You can Disable a source at any time (the agent has none of its tools and its slot in the source quota is freed) or Delete it. Enabling a source manually also resets the circuit breaker (see troubleshooting). Every policy change, tool enablement and source addition is written to the account's audit trail.

11.7Limits of external MCP sources

The Kolio agent uses at most 5 active sources and at most 15 external tools in total; older sources fill the quota first (by creation date), anything beyond it never reaches the model, and the External tool quota card shows which tools are active and which are out of quota.

A transport failure (timeout, HTTP 5xx, unreachable server) counts towards the circuit breaker; a business error ("item not in stock") does not — your server can refuse any number of requests without Kolio suspending the source.

11.8How does Kolio protect the connection to an external source?

Kolio treats an external MCP server as an untrusted source: it checks the URL against private networks, encrypts the credential, sanitises tool descriptions and results, and gives the model a standing instruction that results of external tools are data, not instructions.

11.9What happens when a source stops working?

When an external source fails, the Kolio agent does not break off the conversation: the tool returns a message that the system did not respond in time, the agent does not retry, tells the customer the state is unconfirmed and carries on — after three consecutive transport failures Kolio removes the source from the tool list for 5 minutes.

• "The system did not respond in time" during a call: your server needs more than 4 s (read) or 8 s (write). Shorten the response or pre-compute the data; in web chat the limits are 10 s and 12 s.
• The agent does not use a tool although it is enabled: check the quota (External tool quota), the age of the tool list and whether the source is among the first 5 active ones. Tools are read from the cache at the start of a conversation, so changes apply from the next conversation.
• A write tool cannot be enabled: the source policy is Read only or the tool has no readOnlyHint annotation. Switch the policy or add annotations on the server.
• Adding a source rejects the URL: the address is not https://, uses a non-standard port or resolves to a private network. Expose the server on a public hostname with a valid certificate.
• An external client does not see a Kolio tool (the other direction): the key lacks a scope — create a new key with the required scopes; the scopes of an existing key cannot be edited.