MCP strežnik

Model Context Protocol (MCP) je odprt standard, prek katerega AI asistenti in agenti (Claude, Cursor, VS Code Copilot, OpenAI in Anthropic API) kličejo zunanja orodja. Oddaljeni MCP strežnik maticna.si ponudi register FURS kot 11 orodij samo za branje: iskanje, poizvedbo po ID-ju, paketno poizvedbo, preverjanje DDV in davčne številke, spremembe in zgodovino sprememb, spremljane davčne številke, finančne podatke iz letnih poročil AJPES, šifrante in porabo. Asistent jih pokliče sam, ko vprašanje to zahteva (»Ali je SI80267432 zavezanec za DDV?«).


URL	`https://mcp.maticna.si/mcp`
Transport	Streamable HTTP (samo `POST`, odgovori JSON, brez sej)
Avtentikacija	`Authorization: Bearer mk_…` (API ključ)
Obračun	Enako kot REST: iste enote, ista kvota, iste omejitve hitrosti

Ključ

MCP uporablja iste API ključe kot REST. Ustvarite ga v nadzorni plošči in ga shranite v spremenljivko okolja; v konfiguracijske datoteke, ki jih morda objavite v git, nikoli ne pišite ključa neposredno.

export MATICNA_API_KEY="mk_…"

Priporočilo: ločen ključ za vsakega asistenta, z nastavljeno mesečno omejitvijo enot. Agent, ki se zacikla, tako porabi največ toliko, kolikor dovolite, ključ pa lahko kadarkoli prekličete, ne da bi to vplivalo na vaš backend.
Sprejmemo skrivne ključe mk_… (tudi starejše mk_live_…). Testnih ključev in peskovnika ni več: MCP vedno vrača prave podatke in je obračunan po enotah. Nekdanji ključi mk_test_… vrnejo 401 test_keys_removed.
Javni ključi mk_pub_ vrnejo 401: ključ, omejen na izvor v brskalniku, ne sme postati poverilnica agenta.
Namesto Authorization lahko uporabite glavo X-API-Key.
Ključ v URL-ju (?api_key=…) vrne 400 in ključ samodejno prekličemo, kot pri REST.
Prijave z OAuth (»Sign in to maticna.si«) še ni. Zato se maticna.si še ne poveže z ChatGPT in z imenikom povezav v claude.ai (glej omejitve).

Namestitev

Dodajte strežnik z ukazom (lupina vstavi vrednost spremenljivke; ključ se shrani v vašo lokalno konfiguracijo Claude Code):

claude mcp add --transport http maticna https://mcp.maticna.si/mcp \
  --header "Authorization: Bearer ${MATICNA_API_KEY}"

Za skupni projekt raje uporabite .mcp.json v korenu repozitorija. Claude Code razširi ${MATICNA_API_KEY} ob zagonu, zato je datoteko varno objaviti v git; vsak razvijalec nastavi svoj ključ v okolju.

{
  "mcpServers": {
    "maticna": {
      "type": "http",
      "url": "https://mcp.maticna.si/mcp",
      "headers": {
        "Authorization": "Bearer ${MATICNA_API_KEY}"
      }
    }
  }
}

Preverite z claude mcp list ali /mcp v seji.

V ~/.cursor/mcp.json (vsi projekti) ali .cursor/mcp.json (en projekt). ${env:…} prebere spremenljivko okolja:

{
  "mcpServers": {
    "maticna": {
      "url": "https://mcp.maticna.si/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MATICNA_API_KEY}"
      }
    }
  }
}

V .vscode/mcp.json. VS Code vas ob prvem zagonu vpraša za ključ in ga shrani varno; v datoteki ga ni:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "maticna-api-key",
      "description": "maticna.si secret API key (mk_…)",
      "password": true
    }
  ],
  "servers": {
    "maticna": {
      "type": "http",
      "url": "https://mcp.maticna.si/mcp",
      "headers": {
        "Authorization": "Bearer ${input:maticna-api-key}"
      }
    }
  }
}

Orodja so na voljo v načinu agenta (Copilot Chat → Agent).

MCP konektor v Messages API (beta). Vrednost authorization_token se pošlje kot Bearer, zato vpišite ključ brez predpone:

curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: mcp-client-2025-11-20" \
-d '{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "messages": [{"role": "user", "content": "Ali je SI80267432 zavezanec za DDV?"}],
  "mcp_servers": [{
    "type": "url",
    "url": "https://mcp.maticna.si/mcp",
    "name": "maticna",
    "authorization_token": "'"$MATICNA_API_KEY"'"
  }],
  "tools": [{"type": "mcp_toolset", "mcp_server_name": "maticna"}]
}'

Orodje mcp v Responses API. Ključ gre v polje authorization (brez predpone Bearer); OpenAI ga ne shrani, zato ga pošljete z vsako zahtevo:

curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
  "model": "gpt-6-astra",
  "input": "Ali je SI80267432 zavezanec za DDV?",
  "tools": [{
    "type": "mcp",
    "server_label": "maticna",
    "server_url": "https://mcp.maticna.si/mcp",
    "authorization": "'"$MATICNA_API_KEY"'",
    "require_approval": "never"
  }]
}'

Vsa orodja so samo za branje, zato je require_approval: "never" varna izbira; vsak klic pa porabi enote.

Drugi odjemalci, ki podpirajo oddaljene strežnike Streamable HTTP z lastnimi glavami (npr. LangChain langchain-mcp-adapters, OpenAI Agents SDK), delujejo z istim URL-jem in glavo Authorization: Bearer ….

claude.ai in ChatGPT

claude.ai, Claude Desktop: ročno dodan konektor (»Add custom connector«) zaenkrat podpira lastne glave le v omejeni beta različici, samo za lastnike organizacije, in ključ si deli vsa organizacija. Če te možnosti nimate, uporabite Claude Code ali počakajte na prijavo z OAuth.
ChatGPT sprejme samo OAuth, zato maticna.si tam še ne deluje.

Orodja in cena

Vsako orodje je samo za branje in je obračunano natanko kot ustrezen klic REST.

Orodje	Namen	Enote	Kot REST
`search_entities`	Iskanje podjetij in s.p. po imenu ali filtriranje po kraju, pošti, dejavnosti, DDV, pravni obliki. Do 20 na stran, kurzor.	1	`GET /v1/entities`
`get_entity`	Celoten zapis po davčni številki, ID za DDV (SI…) ali matični (7 ali 10 števk).	1	`GET /v1/entities/{tax}, /by-vat, /by-registration-number`
`lookup_entities`	Do 50 mešanih identifikatorjev v enem klicu. Paket Starter ali višji.	1 na različen ID	`POST /v1/entities/lookup`
`validate_vat_id`	Ali je SIxxxxxxxx veljaven, registriran slovenski ID za DDV na datum podatkov.	1	`GET /v1/vat/validate/{vat}`
`validate_tax_number`	Kontrolna vsota mod-11 in prisotnost na seznamih FURS.	1	`GET /v1/tax-number/validate/{n}`
`list_reference_codes`	Šifranti: dejavnosti SKD, pravne oblike, davčni uradi, poštne številke.	0	`GET /v1/reference/{kind}`
`get_usage`	Paket, porabljene in preostale enote, čas ponastavitve, poraba in mesečna omejitev ključa.	0	`GET /v1/usage`
`list_changes`	Spremembe na seznamih FURS od datuma ali kurzorja naprej (nova podjetja, ukinitve, DDV …), filter po vrsti. Do 50 na stran. Paket Growth ali višji.	1	`GET /v1/changes`
`get_entity_history`	Zgodovina sprememb ene davčne številke (vse registracije), kurzor. Paket Growth ali višji.	1	`GET /v1/entities/{tax}/history`
`list_monitors`	Spremljane davčne številke organizacije in porabljena mesta za spremljanje.	0	`GET /v1/monitors`
`get_financials`	Finančni podatki iz letnih poročil AJPES (prihodki, čisti poslovni izid, zaposleni, sredstva, kapital …) po davčni ali matični, z virom in licenco CC BY 4.0. Nikoli za s.p.	1	`GET /v1/entities/{tax}/financials`

get_entity za pravilno oblikovan identifikator, ki ga ni v registru, vrne found: false in porabi 1 enoto, kot 404 pri REST: »ne obstaja« je odgovor.
lookup_entities je na voljo v paketu Starter in višjih (kot POST /v1/entities/lookup); na paketu Hobi vrne plan_upgrade_required in ne porabi enot. Enote rezervira vnaprej, za vsak različen pravilno oblikovan ID (tudi če ni najden).
list_changes in get_entity_history sta na voljo v paketu Growth in višjih ter zahtevata obseg ključa changes, kot REST. Prva stran začne z since = datum, naslednje nadaljujejo s since = next_cursor. Prikrite osebe se pojavijo le kot zakriti dogodki (redacted: true). Zgodovina neznane, pravilno oblikovane davčne številke vrne napako not_found in porabi 1 enoto, kot 404 pri REST.
list_monitors je brezplačen in zahteva obseg monitors; spremljane številke dodajate v nadzorni plošči ali prek REST (od paketa Starter).
get_financials vrne isti objekt kot GET /v1/entities/{tax}/financials, z enakim dostopom po paketih (od paketa Starter; na paketu Hobi plan_upgrade_required brez porabe enot) in 1 enoto na klic. Sprejme tudi matično številko. Za samostojnega podjetnika (s.p.) vrne coverage.status: not_covered in nobenih številk. Navedbo vira source.attribution (»Vir: AJPES …«, CC BY 4.0) ohranite ob podatkih, ki jih posredujete naprej.
Samodokončanja prek MCP ni; za iskanje uporabite search_entities.
Vsak rezultat iz registra (iskanje, poizvedba, paketna poizvedba, preverjanje) vsebuje data_as_of in source: "Vir: FURS", list_reference_codes pa data_as_of. Metapodatek _meta["si.maticna/usage"] vsakega rezultata pove porabljene in preostale enote, da agent lahko načrtuje porabo.
Podatki o s.p. so osebni podatki. Veljajo iste dnevne omejitve in iste omejitve globine kot pri REST ter pogoji uporabe (brez profiliranja in tržnih seznamov).

Poraba in omejitve

MCP in REST si delita isti števec. Klic orodja se zapiše pod isti ključ in isto organizacijo kot klic REST, zato:

velja ista mesečna kvota paketa, ista dnevna omejitev in morebitna mesečna omejitev ključa;
velja isti proračun hitrosti (burst) na organizacijo: vzporedni klici REST in MCP se seštevajo;
se poraba prikaže v istih grafih v nadzorni plošči, opozorila pri 80 % in 100 % pa upoštevajo oboje;
je preseganje (overage) obračunano enako.

Protokolna sporočila (initialize, tools/list) so brezplačna in ne porabijo proračuna hitrosti, zato asistent vidi orodja tudi, ko je kvota porabljena. get_usage in list_reference_codes delujeta tudi pri 100 % kvote.

Odjemalec, ki izgubi odgovor, klic ponovi in ponovitev je obračunana znova, tako kot ponovljen klic REST brez Idempotency-Key.

Napake

Napake ključa so napake HTTP, vse ostalo vrnemo kot rezultat orodja z isError: true, da ga model lahko prebere in uporabniku razloži. Napake ne porabijo enot.

Primer	Odgovor
Brez ključa, neveljaven, preklican ali potekel ključ, ključ `mk_pub_`	HTTP 401 (invalid_api_key)
Ključ v URL-ju	HTTP 400 in samodejni preklic (key_in_query_forbidden)
IP ni na seznamu dovoljenih	HTTP 403 (ip_not_allowed)
Kvota porabljena, preveč zahtev	`isError`, `code` quota_exceeded ali rate_limited, `retry_after_seconds`
Ključ nima pravice, paket ne vključuje funkcije, neplačan račun	`isError`, insufficient_scope, plan_upgrade_required, payment_required
Napačna kontrolna vsota, prekratko iskanje	`isError`, npr. invalid_tax_number, query_too_short
Podatki osveženi med listanjem	`isError`, cursor_expired: iskanje ponovite brez `cursor`
Dnevna omejitev fizičnih oseb	`isError`, natural_person_cap_exceeded

Oblika napake je enaka za vsa orodja. Model bere content, programi _meta["si.maticna/error"] (rezultat z napako nima structuredContent). Paketov JSON-RPC (batch) ne podpiramo (HTTP 400): pošljite eno zahtevo na POST.

{
  "isError": true,
  "content": [{ "type": "text", "text": "quota_exceeded: The monthly quota of 25000 units is used up. Resets 2026-11-01T00:00:00+01:00." }],
  "_meta": {
    "si.maticna/error": { "code": "quota_exceeded", "status": 429, "retry_after_seconds": 1036800, "request_id": "req_…" },
    "si.maticna/usage": { "units_charged": 0, "units_remaining": 0, "period_end": "…", "request_id": "req_…" }
  }
}

Preizkus

MCP nima peskovnika: vsak klic orodja dela na pravih podatkih in porabi enote kot REST. Za razvoj ustvarite ločen ključ z nizko mesečno omejitvijo enot, da agent ne more porabiti več, kot dovolite. Posamezne zahteve REST lahko brezplačno preizkusite v preizkuševalniku API-ja v nadzorni plošči.

Za ročni preizkus uporabite MCP Inspector (npx @modelcontextprotocol/inspector, transport Streamable HTTP, glava Authorization).

Vir: FURS · neuradni vir, ni uradni izpis · Pogoji · Zasebnost · maticna.si