MCP — Model Context Protocol

Čo je MCP

Model Context Protocol je otvorený štandard od Anthropic na pripojenie LLM aplikácií k externým dátovým zdrojom a nástrojom. AI klient (Claude Desktop, vlastná aplikácia) si prečíta zoznam dostupných nástrojov z MCP servera a sám sa rozhoduje, ktorý zavolať na základe konverzácie s používateľom.

Veritra MCP server beží ako HTTP transport — žiadne lokálne procesy, len jeden POST endpoint, ktorý prijíma JSON-RPC requesty.

Endpoint a autentifikácia

Použite management API kľúč (mrw_…) v Authorization hlavičke. Hlavička X-MRW-Client: mcp signalizuje, že volanie prichádza z MCP klienta (interne používané na sledovanie audience a kontrolu oprávnení).

Authorization: Bearer mrw_7fa7785c3d6e…
X-MRW-Client: mcp
Content-Type: application/json

Kľúč nájdete v dashboarde po onboardingu. Rovnaký kľúč funguje pre REST aj pre MCP — žiadne samostatné nastavenie.

JSON-RPC envelope

Každý request aj response sa riadi špecifikáciou JSON-RPC 2.0. tools/list pre discovery, tools/call pre volanie nástroja.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tenders_search",
    "arguments": { "qText": "rekonstrukce mostu", "limit": 10 }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "{ … JSON payload … }" }]
  }
}

Pri chybe je v response objekt error namiesto result:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": { "code": -32602, "message": "Invalid params: qText is required" }
}

Discovery (tools/list)

Klient si prečíta zoznam dostupných nástrojov — server vracia MCP-štandardné definície nástrojov vrátane JSON schémy pre parametre.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Response obsahuje pole tools[] s objektmi { name, description, inputSchema }. AI klient používa inputSchema na validáciu argumentov.

Katalóg nástrojov

Aktuálne 9 nástrojov v 4 kategóriách: tenders (search/detail/filters), leads (filters), accounts, subscriptions, meta.

tenders_search

Live vyhľadávanie tendrov naprieč všetkými portálmi. Vráti top N tendrov s detailom (title, value, deadline, contracting authority, …).

tenders_get_detail

Detail jedného tendru vrátane documents + príznakov preferencií.

tenders_list_industries

Vráti zoznam industry tagov (con_buildings, it_development, …) na filtrovanie — agent môže LLM zobraziť používateľsky prívetivé menu namiesto prepisovania IDs.

tenders_list_regions

Vráti zoznam NUTS regiónov pre danú krajinu (CZ predvolené).

leads_list_filters

Zoznam uložených LEADS filtrov používateľa.

Filtre vytvorené cez MCP / REST sa používajú aj v e-mailoch, push notifikáciách a webhookoch — agent môže nastaviť a používateľ ich dostane štandardnými kanálmi.

leads_create_filter

Vytvorí nový LEADS filter. Pri ďalších zhodách na zákazkách sa spustí webhook + e-mailový digest.

account_create_webhook

Zaregistruje HTTPS webhook endpoint pre príjem eventov (leads.match.created atď.). Vráti endpoint id + secret pre HMAC verifikáciu. Secret sa zobrazí IBA raz — uložte ho do svojho ENV.

Max 5 endpointov na účet. Pre rotáciu secretu použite /api/v2/account/webhooks/:id/rotate-secret.

subscriptions_list_plans

Verejný katalóg služieb a cien (LEADS, PRICING, PROCUREMENT). Bez autentifikácie.

meta_list_services

Stav všetkých služieb Tendera (uptime, príznaky zastarania).

curl príklad

Vyhľadanie top 5 stavebných zákaziek nad 1M Kč v Prahe:

curl -X POST https://veritra.io/api/mcp \
  -H "Authorization: Bearer mrw_…" \
  -H "X-MRW-Client: mcp" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "tenders_search",
      "arguments": {
        "industryTags": ["con_buildings"],
        "regions": ["CZ010"],
        "minValue": 1000000,
        "limit": 5
      }
    }
  }'

Nastavenie v Claude Desktop

Pridaj do ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) alebo ekvivalentu:

{
  "mcpServers": {
    "veritra": {
      "url": "https://veritra.io/api/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer mrw_…",
        "X-MRW-Client": "mcp"
      }
    }
  }
}

Po reštarte Claude Desktop uvidíš v UI ikonku pripojeného MCP servera. Otvor konverzáciu a opýtaj sa napr. 'Aké sú aktuálne stavebné zákazky v Prahe nad milión?' — Claude sám zavolá tenders_search.

Iní MCP klienti

MCP server beží ako HTTP transport — kompatibilný s ľubovoľným klientom, ktorý podporuje JSON-RPC 2.0 cez HTTP. Nižšie sú príklady pre najčastejšie používané.

Cursor / Continue / Cline / Zed

Cursor IDE má built-in MCP support. Edituj ~/.cursor/mcp.json:

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "veritra": {
      "url": "https://veritra.io/api/mcp",
      "headers": {
        "Authorization": "Bearer mrw_mgmt_…",
        "X-MRW-Client": "mcp"
      }
    }
  }
}

Continue.dev

Open-source VS Code rozšírenie. Pridaj do config.json:

// ~/.continue/config.json (snippet)
"mcpServers": [
  {
    "name": "veritra",
    "transport": { "type": "http", "url": "https://veritra.io/api/mcp" },
    "requestOptions": {
      "headers": {
        "Authorization": "Bearer mrw_mgmt_…",
        "X-MRW-Client": "mcp"
      }
    }
  }
]

Generic HTTP MCP klient / ChatGPT plugin / vlastný LLM

Ak klient nemá natívnu MCP podporu, komunikuj s API priamo cez JSON-RPC 2.0. Hlavičky Authorization + X-MRW-Client identifikujú váš účet. Discovery (tools/list) je prvé volanie.

POST https://veritra.io/api/mcp HTTP/1.1
Authorization: Bearer mrw_mgmt_<your_key>
X-MRW-Client: mcp
Content-Type: application/json

{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }

Rate limity

MCP volania spadajú pod rovnaké mgmt API limity (60/min read, 10/min write, 5000/deň). Pri prekročení vracia HTTP 429 (JSON-RPC error code -32000).