Kolio MCP strežnik in zunanji MCP viri

11.1Kateri dve smeri MCP Kolio podpira?

MCP (Model Context Protocol) je odprt protokol (specifikacija modelcontextprotocol.io), po katerem AI odjemalec od strežnika dobi seznam orodij s shemami vhoda in jih kliče prek JSON-RPC 2.0; Kolio ga uporablja kot strežnik (vaši podatki za zunanje agente) in kot odjemalec (podatki vaših sistemov za Koliov agent).

Obe smeri upravljate na eni strani, Nastavitve → MCP viri in integracije. Zgornji razdelek Kolio kot vir za zunanje sisteme vsebuje naslov MCP strežnika, API ključe in webhooke; spodnji razdelek Zunanji viri v Koliu vsebuje obrazec Dodaj strežnik in seznam povezanih virov.

11.2Kako povežem Claude ali drug odjemalec na Kolio MCP strežnik?

Kolio MCP strežnik je na naslovu https://kolio.si/api/mcp; odjemalec potrebuje ta URL in glavo Authorization: Bearer kolio_sk_… z API ključem, ki ga ustvarite v Koliu — vsak odjemalec, ki podpira oddaljene MCP strežnike prek Streamable HTTP, se poveže brez dodatne programske opreme.

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.3Katera orodja ponuja Kolio MCP strežnik?

Kolio MCP strežnik ponuja 21 orodij — 9 za koledar in 12 za CRM — in vsako zahteva natanko en obseg ključa; tools/list vrne samo orodja, za katera ima ključ obseg, tako da odjemalec nikoli ne vidi orodja, ki bi mu bilo zavrnjeno.

Strežnik ob initialize odjemalcu pošlje kratko navodilo: podatke najprej poišči (list_events, find_free_slots, list_contacts, list_tasks) in šele nato ustvarjaj ali spreminjaj, da ne nastanejo podvojeni kontakti ali prekrivajoči se termini. Id-ji iz bralnih orodij so vhod za pisalna. Pisalna orodja sprožijo iste webhooke kot REST (booking.created, booking.cancelled, contact.created, task.created, task.updated).

11.4Primer klica: JSON-RPC prek curl

Kolio MCP strežnik uporablja transport Streamable HTTP brez stanja: vsak klic je en POST na https://kolio.si/api/mcp z JSON-RPC 2.0 telesom in enim JSON odgovorom; različica protokola je 2025-06-18, ime strežnika kolio, podprte metode so initialize, ping, tools/list in 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"}'

# odgovor (skrajšano)
{ "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": "<id storitve>", "date_from": "2026-09-21", "date_to": "2026-09-25" }
    }
  }'

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

# poslovna napaka (uspešen JSON-RPC odgovor, agent jo lahko popravi)
{ "jsonrpc": "2.0", "id": 2,
  "result": { "isError": true, "content": [ { "type": "text", "text": "Termin je že zaseden." } ] } }

11.5Kako povežem svoj sistem kot MCP vir v Kolio?

Zunanji MCP vir dodate v razdelku Zunanji viri v Koliu na strani Nastavitve → MCP viri in integracije; vir potrebuje ime, https:// naslov Streamable HTTP končne točke in po potrebi poverilnico, po dodajanju pa ga s klikom Preveri povezavo odkrijete in vsako orodje posebej vklopite.

11.6Politika orodij in seznam dovoljenih orodij

Pisanje v vaš sistem zahteva dve zavestni odločitvi: politiko Dovoli tudi spreminjanje podatkov na viru in vklop posameznega pisalnega orodja v seznamu dovoljenih; privzeta politika je Samo branje, seznam dovoljenih orodij je ob dodajanju prazen in ga osvežitev ne širi sama.

Vir lahko kadar koli Izklopite (agent nima nobenega njegovega orodja, mesto v kvoti virov se sprosti) ali Izbrišete. Ročni vklop vira hkrati ponastavi prekinjevalnik (glej odpravljanje težav). Vsaka sprememba politike, vklop orodja in dodajanje vira se zapišejo v revizijsko sled računa.

11.7Omejitve zunanjih MCP virov

Koliov agent uporablja največ 5 aktivnih virov in skupno največ 15 zunanjih orodij; kvoto polnijo starejši viri prvi (po datumu nastanka), kar presega, do modela ne pride, kartica Kvota zunanjih orodij pa pokaže, katera orodja so aktivno in katera zunaj kvote.

Transportna napaka (časovni rok, HTTP 5xx, nedosegljiv strežnik) šteje v prekinjevalnik; poslovna napaka (»artikla ni na zalogi«) ne šteje — vaš strežnik lahko zavrne poljubno število zahtev, ne da bi Kolio vir izločil.

11.8Kako Kolio varuje povezavo z zunanjim virom?

Kolio zunanji MCP strežnik obravnava kot nezaupen vir: URL preveri proti zasebnim omrežjem, poverilnico šifrira, opise in rezultate orodij očisti, model pa dobi trajno navodilo, da so rezultati zunanjih orodij podatki in ne navodila.

11.9Kaj se zgodi, ko vir ne deluje?

Ko zunanji vir odpove, Koliov agent pogovora ne prekine: orodje vrne sporočilo, da se sistem ni odzval pravočasno, agent klica ne ponovi, sogovorniku pove, da stanje ni potrjeno, in nadaljuje — po treh zaporednih transportnih napakah pa Kolio vir za 5 minut izloči iz seznama orodij.

• »Sistem se ni odzval pravočasno« med klicem: vaš strežnik potrebuje več kot 4 s (branje) oz. 8 s (pisanje). Skrajšajte odziv ali podatke predpripravite; v spletnem klepetu sta roka 10 s in 12 s.
• Agent orodja ne uporabi, čeprav je vklopljeno: preverite kvoto (Kvota zunanjih orodij), starost seznama in ali je vir med prvimi 5 aktivnimi. Orodja se berejo iz predpomnilnika ob začetku pogovora, zato spremembe veljajo od naslednjega pogovora.
• Pisalnega orodja ni mogoče vklopiti: politika vira je Samo branje ali orodje nima anotacije readOnlyHint. Preklopite politiko ali dopolnite anotacije na strežniku.
• Dodajanje vira zavrne URL: naslov ni https://, uporablja nestandardna vrata ali se razreši v zasebno omrežje. Strežnik izpostavite na javnem imenu z veljavnim certifikatom.
• Zunanji odjemalec ne vidi orodja Kolia (obratna smer): ključu manjka obseg — ustvarite nov ključ s potrebnimi obsegi; obsegov obstoječega ključa ni mogoče urejati.