MCP — Model Context Protocol

Co je MCP

Model Context Protocol je otevřený standard od Anthropic pro připojení LLM aplikací k externím datovým zdrojům a nástrojům. AI klient (Claude Desktop, custom app) si přečte seznam dostupných tools z MCP serveru a sám se rozhoduje, který zavolat na základě konverzace s uživatelem.

Tendero MCP server běží jako HTTP transport — žádné lokální procesy, jen jeden POST endpoint který přijímá JSON-RPC requesty.

Endpoint a autentizace

Použij management API key (mrw_…) v Authorization headeru. Hlavička X-MRW-Client: mcp signalizuje, že volání jde z MCP klienta (interně použito pro audience tracking a entitlement check).

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

Klíč najdeš v dashboardu po onboardingu. Stejný klíč funguje pro REST i pro MCP — žádný separátní setup.

JSON-RPC envelope

Každý request a response se řídí JSON-RPC 2.0 specifikací. tools/list pro discovery, tools/call pro volání nástroje.

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 … }" }]
  }
}

Při chybě je v response error objekt místo result:

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

Discovery (tools/list)

Klient si přečte seznam dostupných tools — server vrací MCP-standard tool definitions včetně JSON schema pro parametry.

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

Response obsahuje pole tools[] s objekty { name, description, inputSchema }. AI klient používá inputSchema pro validaci argumentů.

Katalog nástrojů

Aktuálně 9 nástrojů ve 4 kategoriích: tenders (search/detail/filters), leads (filters), accounts, subscriptions, meta.

tenders_search

Live search tendrů napříč všemi portály. Vrátí top N tendrů s detailem (title, value, deadline, contracting authority, …).

tenders_get_detail

Detail jednoho tendru včetně documents + preference flags.

tenders_list_industries

Vrátí seznam industry tagů (con_buildings, it_development, …) pro filtrování — agent může LLM ukázat user-friendly menu místo opisování IDs.

tenders_list_regions

Vrátí seznam NUTS regionů pro danou zemi (CZ default).

leads_list_filters

List uložených LEADS filtrů usera.

Filtry vytvořené přes MCP / REST se používají i v emaillech, push notifikacích a webhookech — agent může nastavit a uživatel je dostane standardními kanály.

leads_create_filter

Vytvoří nový LEADS filter. Při dalších match na zakázky se trigger webhook + email digest.

account_create_webhook

Zaregistruje HTTPS webhook endpoint pro příjem eventů (leads.match.created atd.). Vrátí endpoint id + secret pro HMAC verifikaci. Secret se zobrazí JEN jednou — ulož ho do svého ENV.

Max 5 endpointů na účet. Pro rotaci secretu použij /api/v2/account/webhooks/:id/rotate-secret.

subscriptions_list_plans

Veřejný katalog služeb a cen (LEADS, PRICING, PROCUREMENT). Bez auth.

meta_list_services

Stav všech services Tendera (uptime, deprecation flags).

curl příklad

Vyhledání top 5 stavebních zakázek nad 1M Kč v Praze:

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
      }
    }
  }'

Setup v Claude Desktop

Přidej do ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) nebo ekvivalentu:

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

Po restartu Claude Desktop uvidíš v UI ikonku připojeného MCP serveru. Otevři conversation a zeptej se např. 'Jaké jsou aktuální stavební zakázky v Praze nad milion?' — Claude sám zavolá tenders_search.

Jiní MCP klienti

MCP server běží jako HTTP transport — kompatibilní s libovolným klientem který podporuje JSON-RPC 2.0 přes HTTP. Níže příklady pro nejčastější.

Cursor / Continue / Cline / Zed

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

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

Continue.dev

Open-source VS Code rozšíření. Přidej do config.json:

// ~/.continue/config.json (snippet)
"mcpServers": [
  {
    "name": "tendero",
    "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

Pokud klient nemá nativní MCP support, mluv s API přímo přes JSON-RPC 2.0. Záhlavi Authorization + X-MRW-Client identifikují tvůj účet. Discovery (tools/list) je první volání.

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 volání spadají pod stejné mgmt API limity (60/min read, 10/min write, 5000/den). Při překročení vrací HTTP 429 (JSON-RPC error code -32000).