AI agenti (MCP)

Pripojte Claude, Cursor a iných MCP klientov k vlastnej inštancii cez MCP endpoint len na čítanie, s rovnakými kľúčmi, limitmi a pravidlami ako REST API.

Vaša inštancia môže sprístupniť Model Context Protocol, aby AI agent sám vyhľadával a overoval slovenské firmy. Je predvolene vypnutý a len na čítanie. Každé volanie nástroja ide cez REST API v tom istom procese, takže agent dostane presne to, čo program, s tým istým API kľúčom, limitom a pravidlami logovania.

Neexistuje centrálny server: vaši agenti komunikujú s vašou inštanciou a k správcom Accquix sa nič nedostane. Pre agenta, ktorého si stavate sami, je zvyčajne jednoduchšie volať REST API s vlastnými definíciami nástrojov; MCP je pre agentov, ktorých nestavate, napríklad Claude Desktop, Claude Code alebo Cursor.

Zapnutie

REGISTER_MCP=true    # /mcp vedľa /v1

GET /v1/capabilities potom uvádza "mcp": { "enabled": true, "path": "/mcp" }. Endpoint používa Streamable HTTP bez relácií: POST /mcp, jedna JSON odpoveď na požiadavku.

Nástroje

Nástroj	Robí	To isté ako
`search_subjects`	Kandidáti pre názov, IČO, DIČ alebo IČ DPH; `mode` `fuzzy` len ak je zapnutý	`GET /v1/search`
`lookup_subject`	Subjekt s časťami, stavmi a dátumami aktuálnosti	`GET /v1/lookup/{id}`
`get_data_freshness`	Stav a dátum aktuálnosti každého zdroja	`GET /v1/sources`

Každý výsledok nesie telo REST odpovede ako štruktúrovaný obsah a krátke zhrnutie, ktoré končí uvedením zdroja. Popisy nástrojov naučia agenta pravidlá, ktoré by vývojár čítal tu: výsledok vyhľadávania je kandidát, nie fakt; unknown nikdy neznamená „nenájdené“; §7 a §7a sú registrované, ale nie sú platiteľmi DPH; jedno IČ DPH môže patriť viacerým subjektom. 503 sa zmení na chybu nástroja, ktorá to povie slovami, takže agent si výpadok nepomýli s „nenájdené“.

Presný zoznam nástrojov so všetkými schémami je v repozitári ako api/mcp-tools.json.

Pripojenie klienta

Nechajte svojho AI agenta pripojiť MCP nástroje registra k vášmu klientovi.

claude mcp add --transport http accquix-register https://register.example.internal/mcp \
  --header "Authorization: Bearer $REGISTER_KEY"

V .cursor/mcp.json:

{
  "mcpServers": {
    "accquix-register": {
      "url": "https://register.example.internal/mcp",
      "headers": { "Authorization": "Bearer ${env:REGISTER_KEY}" }
    }
  }
}

Claude Desktop spúšťa lokálne servery cez stdio, preto použite lokálny adaptér. Každé volanie posiela do REST API vašej inštancie a k databáze sa nikdy nepripája. V claude_desktop_config.json:

{
  "mcpServers": {
    "accquix-register": {
      "command": "accquix-register",
      "args": ["mcp", "--url", "https://register.example.internal"],
      "env": { "REGISTER_MCP_KEY": "<váš API kľúč>" }
    }
  }
}

Každému agentovi dajte vlastný API kľúč: meno kľúča je v logoch a má vlastný limit požiadaviek.

Bezpečnosť

Len na čítanie. Žiadny nástroj nemôže meniť dáta, námietky ani nastavenia a žiadny taký nepribudne.
Rovnaké kľúče a limity ako REST. Chýbajúci alebo nesprávny kľúč dostane HTTP 401; volanie nástroja stojí jednu požiadavku z rozpočtu volajúceho. Anonymné inštancie si zachovávajú svoje obmedzenia vrátane zákazu overenia fyzických osôb podľa DIČ.
Stránky v prehliadači sa odmietnu. Požiadavka z webovej stránky iného pôvodu dostane 403, ako ochrana proti DNS rebindingu. Konkrétne pôvody povoľte cez REGISTER_MCP_ALLOWED_ORIGINS, len ak si stavate vlastného klienta v prehliadači.
Logy. Požiadavka na /mcp a jeden riadok na volanie nástroja s jeho menom a stavom; nikdy dopyt, identifikátor ani výsledok.
Dáta, nie pokyny. Názvy firiem vo výsledkoch pochádzajú z verejných registrov. Server agentovi hovorí, aby ich bral ako dáta, no agent, ktorý koná sám (posiela e-maily, platí faktúry), by mal aj tak potvrdiť s človekom.