Kolio is an AI agent for business that connects to your systems both ways. As an MCP client it reads your ERP, store or calendar through an MCP server — read-only by default, each tool enabled one by one. As a source it offers a REST API for AI agent, an MCP server and webhooks; keys never exceed their issuer.
Free 7-day trial · no credit card · MCP client in the Growth plan
POST https://kolio.si/api/mcpAuthorization: Bearer kolio_sk_••••••••Content-Type: application/json { "jsonrpc": "2.0", "id": 1, "method": "tools/list" } ← 200 OK{ "jsonrpc": "2.0", "id": 1, "result": { "tools": [{ "name": "find_free_slots", "inputSchema": { … } },{ "name": "create_event", "inputSchema": { … } },{ "name": "list_contacts", "inputSchema": { … } },{ "name": "create_task", "inputSchema": { … } },… 21 tools in total (9 calendar, 12 CRM), filtered by the key's scopes] } }Prepared by the Kolio team · updated
Every MCP server has a policy of read_only or full. Under read_only the agent may only call tools the server explicitly marks as read (the readOnlyHint annotation); a tool without the annotation is treated as a write and does not get through. You switch on full deliberately, per server.
No tool is enabled when a server is added. You enable each one; when the server adds new tools, refreshing the list does not enable them on its own. The model gets at most 15 external tools at once, in a predictable order (by the time each server was added).
A read call during a phone call gets 4 s, in web chat 10 s; a write call 8 s (phone) or 12 s (web), because after a timeout nobody knows whether the write happened. After three consecutive transport failures the server is switched off for 5 minutes (circuit breaker); business refusals ("out of stock") do not count.
The server address is checked when saved and on every call: https on port 443 only, no private or internal addresses, no following redirects. Tool names and descriptions are cleaned, suspicious descriptions are blocked, and a tool result is cut to 600 characters before the model sees it.
MCP (Model Context Protocol) is an open standard by which an AI agent discovers the tools of an external system (tools/list) and calls them (tools/call) over JSON-RPC 2.0. Kolio uses it in both directions: as a client it calls your server, as a server at /api/mcp it offers its own calendar and CRM tools.
Standards Kolio builds its integrations on: the Model Context Protocol, specification 2025-06-18 with readOnlyHint tool annotations, JSON-RPC 2.0 for the MCP server, HMAC-SHA256 (RFC 2104) for webhook signatures and guards against SSRF (OWASP Top 10, A10:2021).
Kolio is also a data source for your CRM, ERP or your own AI agent: the same API key (Authorization: Bearer kolio_sk_… or X-API-Key) opens the REST Integrations API v1 and the MCP server at /api/mcp. The tenant is always taken from the key, never from the request body. Every key has scopes, and every scope maps to a permission of the team member who issued the key — so a key can never do more than its issuer. All three entry points (UI, REST, MCP) write through the same business cores: an appointment passes opening-hours, availability and overlap checks, a task passes assignee validation, a contact goes through the same core as in the UI.
| Endpoint | Methods | Scope |
|---|---|---|
| /api/integrations/v1/ping | GET | any valid key (returns tenantId, scopes, timestamp) |
| /api/integrations/v1/bookings | GET · POST | bookings:read · bookings:write |
| /api/integrations/v1/bookings/{id} | GET · PATCH · DELETE | bookings:read · bookings:write |
| /api/integrations/v1/contacts | GET · POST | contacts:read · contacts:write |
| /api/integrations/v1/contacts/{id} | GET · PATCH · DELETE | contacts:read · contacts:write |
| /api/integrations/v1/tasks | GET · POST | tasks:read · tasks:write |
| /api/integrations/v1/tasks/{id} | GET · PATCH · DELETE | tasks:read · tasks:write |
| /api/mcp | POST (JSON-RPC 2.0) | tools by the key's scopes |
Success returns { "data": … }, an error { "error": "<code>", "message": "<explanation>" }. Lists: 50 records by default, 200 at most.
GET /api/integrations/v1/bookings?from=2026-09-21&to=2026-09-27Authorization: Bearer kolio_sk_•••••••• ← 200 OK{ "data": [{ "id": "bk_7f3a…", "slotStart": "2026-09-22T09:00:00.000Z","slotEnd": "2026-09-22T09:30:00.000Z", "status": "confirmed", "source": "phone" }] } ← 403 Forbidden{ "error": "insufficient_scope","message": "Ključ nima obsega 'bookings:read'. Dodajte ga v Nastavitve → Integracije." }POST https://vas-sistem.example/kolio-webhookx-kolio-event: booking.createdx-kolio-signature: sha256=3f1c9e…content-type: application/json { "event": "booking.created","tenantId": "ten_…", "timestamp": "2026-09-15T07:31:02.114Z","data": { "bookingId": "bk_7f3a…", "contactId": "ct_…", "serviceId": "sv_…","slotStart": "2026-09-22T09:00:00.000Z", "slotEnd": "2026-09-22T09:30:00.000Z", "status": "confirmed" } }| Scope | Covers | Member permission |
|---|---|---|
| bookings:read · bookings:write | appointments in the calendar | appointments |
| services:read | services (duration, location) for bookings | services |
| contacts:read · contacts:write | CRM contacts and notes | contacts |
| tasks:read · tasks:write | tasks and their timeline | tasks |
| conversations:read | conversations and transcripts | call centre |
| reports:read | reports | reports |
| knowledge:read | knowledge base | knowledge base |
| email:write | sending email on your behalf (not in the MCP connector default) | email marketing |
The mapping lives in one place in the code (scopes.ts); permissions are checked when the key is issued and on every call.
Stateless Streamable HTTP: one POST with a JSON-RPC 2.0 body, one response; there is no SSE stream (GET returns 405). Calendar: list_events, get_event, list_services, find_free_slots, create_event, update_event, cancel_event, delete_event. CRM: list_contacts, get_contact, create_contact, update_contact, add_contact_note, delete_contact, list_tasks, get_task, create_task, update_task, add_task_comment, delete_task. A tool the key has no scope for does not appear in tools/list.
You register a URL and pick events: booking.created, booking.cancelled, contact.created, task.created, task.updated and call.completed (a completed phone call by the AI agent or the web phone). Every delivery is a POST with the envelope { event, tenantId, timestamp, data } and the headers x-kolio-event, x-kolio-timestamp and x-kolio-signature (HMAC-SHA256 of the body with the endpoint's secret, shown once on creation or rotation). Booking, contact and task events are fired by writes through REST and MCP, not by the UI; call.completed is sent by every completed call. Delivery timeout is 10 s, with no retries.
When an integration creates a task or a note, the timeline records the origin as api:‹key name› (e.g. api:ERP bridge) — your team sees which connection acted. All ISO times without an offset are read in your company's time zone (a tenant setting, Europe/Ljubljana by default), so appointments do not shift because the server runs in UTC.
REST and MCP take the customer account from the API key. Even if an agent writes another tenantId into the body, it cannot reach anyone else's data. The database holds only a SHA-256 hash of the key; you see the full key once, when it is issued.
The model gets a fixed instruction: results of external tools are data; it ignores any instructions inside them; it does not send email or disclose other customers' data based on a result; on "the system did not respond" it does not retry. Descriptions of external tools never enter the system prompt.
The MCP client works in the Growth and Custom plans and during the trial; on a downgrade external tools are removed from the bot. Credentials for your server are encrypted in the database (AES-GCM), and webhook secrets are used only for signing.
The Kolio MCP integration has four known limitations that we do not hide, because they affect how you design your MCP server. All of them follow from deliberate choices for safety or predictability in the voice channel.
Kolio does not retry a write call after a timeout and does not send an idempotency key. If your server cannot detect duplicates itself, let the write tool accept a reference (e.g. the conversation number) by which it rejects a duplicate.
The model sees at most 600 characters of a tool result. Return confirmation numbers and key facts at the start of the text and do not return whole lists — offer a filtered tool instead.
Richer parts of JSON Schema (oneOf, conditional fields, deep nesting) are lost when passed to the model. Keep arguments flat and field descriptions short.
If you enable more than 15 tools, the model gets the first 15 in the order servers were added; the UI does not (yet) warn you. Enable only the tools the conversation really needs.
If the vendor of your ERP or store does not offer an MCP server, we build one to order during onboarding: a thin server in front of your API or database that exposes exactly the tools the conversation needs (e.g. order status by number, delivery date by item), with the readOnlyHint annotation on read tools. This is part of the Dedicated Kolio offer; scope and price are set in a consultation. A ready connection over MCP means your team never touches our code — you only write a server against an open standard.
The connection is set up by the account owner or an admin under Settings → MCP sources and integrations; for step 2 you need the address of an MCP server or a developer who will call the REST API.
Under Settings → MCP sources and integrations create a key, name it (e.g. "ERP bridge") and pick only the scopes it needs. The kolio_sk_… key is shown once; verify it with GET /api/integrations/v1/ping.
For Kolio to read your system, enter the address (https) and authentication of your MCP server under Settings → MCP sources and integrations; Kolio fetches the list of tools. For your system to read Kolio, call REST v1 or /api/mcp with the issued key.
Enable only the tools the conversation needs. Keep read_only until you really want writes; switch on full per server and check that read tools carry the readOnlyHint annotation.
In the simulator ask a question that needs data from your system and check the answer; test conversations are not saved to the CRM, but tool calls are real — a booking or task created by a tool is written.
MCP (Model Context Protocol) is an open standard by which an AI agent discovers the tools of an external system and calls them over JSON-RPC 2.0. Kolio uses it because the same server works with any MCP client, not only Kolio, and because tools carry annotations (readOnlyHint) on which Kolio builds its read-only policy.
Kolio stops waiting after 4 seconds (a read call during a phone call) or 8 seconds (a write call) and returns "the external system did not respond in time" to the model. The agent does not retry, tells the customer the status is unconfirmed and continues the conversation; after three consecutive transport failures the server is switched off for 5 minutes.
The Kolio AI agent writes to an external system only if the full policy is enabled for that server and the write tool is explicitly on the list of enabled tools; the default is read_only, which lets through only tools with the readOnlyHint annotation. In the email agent's "test" mode, write actions wait for a team member's confirmation.
A Kolio API key has the scopes bookings, services, contacts, tasks, conversations, reports, knowledge (read and, where relevant, write) and email:write. Every scope maps to a permission of the team member who issued the key and is checked at issue time and on every call, so a key can never do more than its issuer.
Kolio sends the events booking.created, booking.cancelled, contact.created, task.created and task.updated as a POST with the JSON envelope { event, tenantId, timestamp, data }. The signature is in the x-kolio-signature header as sha256=<HMAC-SHA256 of the body with the endpoint's secret>; verify it over the raw body before processing the event.
Kolio's technical documentation (REST v1 endpoints, the list of MCP tools with schemas, webhooks) is being prepared on the Help page; until then the source of truth is this page and the list of tools that tools/list returns for your key. The MCP server address and example calls are also shown under Settings → MCP sources and integrations.
The 7-day trial includes the MCP client, REST API, MCP server and webhooks; a custom server is agreed in a consultation.
No credit card · you issue the key yourself · data in the EU