MCP — Model Context Protocol

Czym jest MCP

Model Context Protocol to otwarty standard opracowany przez Anthropic, służący do łączenia aplikacji LLM z zewnętrznymi źródłami danych i narzędziami. Klient AI (Claude Desktop, niestandardowa aplikacja) odczytuje listę dostępnych narzędzi z serwera MCP i decyduje, które wywołać na podstawie rozmowy z użytkownikiem.

Serwer Veritra MCP działa jako transport HTTP — żadnych lokalnych procesów, tylko jeden punkt końcowy POST przyjmujący żądania JSON-RPC.

Endpoint i uwierzytelnianie

Użyj klucza Management API (mrw_…) w nagłówku Authorization. Nagłówek X-MRW-Client: mcp sygnalizuje, że wywołanie pochodzi od klienta MCP (używane wewnętrznie do śledzenia odbiorców i weryfikacji uprawnień).

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

Klucz znajdziesz w panelu po zakończeniu onboardingu. Ten sam klucz działa dla REST i MCP — bez osobnej konfiguracji.

Koperta JSON-RPC

Każde żądanie i odpowiedź są zgodne ze specyfikacją JSON-RPC 2.0. tools/list służy do odkrywania narzędzi, tools/call do ich wywoływania.

Żądanie

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

Odpowiedź

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

W przypadku błędu odpowiedź zawiera obiekt błędu zamiast wyniku:

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

Odkrywanie (tools/list)

Klient odczytuje listę dostępnych narzędzi — serwer zwraca standardowe definicje narzędzi MCP, w tym schemat JSON dla parametrów.

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

Odpowiedź zawiera tablicę tools[] z obiektami { name, description, inputSchema }. Klient AI używa inputSchema do walidacji argumentów.

Katalog narzędzi

Aktualnie 9 narzędzi w 4 kategoriach: przetargi (wyszukiwanie/szczegóły/filtry), leady (filtry), konta, subskrypcje, meta.

tenders_search

Wyszukiwanie przetargów w czasie rzeczywistym we wszystkich portalach. Zwraca N najlepszych przetargów ze szczegółami (tytuł, wartość, termin, zamawiający, …).

tenders_get_detail

Szczegóły jednego przetargu, w tym dokumenty i flagi preferencji.

tenders_list_industries

Zwraca listę tagów branżowych (con_buildings, it_development, …) do filtrowania — agent może wyświetlić użytkownikowi przyjazne menu zamiast zapamiętywać identyfikatory.

tenders_list_regions

Zwraca listę regionów NUTS dla danego kraju (domyślnie CZ).

leads_list_filters

Lista zapisanych filtrów LEADS użytkownika.

Filtry utworzone przez MCP / REST są również używane w e-mailach, powiadomieniach push i webhookach — agent może je skonfigurować, a użytkownik otrzymuje je standardowymi kanałami.

leads_create_filter

Tworzy nowy filtr LEADS. Nowe dopasowania wyzwalają webhook + digest e-mail.

account_create_webhook

Zarejestruj endpoint webhooka HTTPS do odbierania zdarzeń (leads.match.created itp.). Zwraca ID endpointu oraz sekret do weryfikacji HMAC. Sekret jest wyświetlany TYLKO RAZ — zapisz go w swoich zmiennych środowiskowych.

Maks. 5 endpointów na konto. Aby obrócić sekret, użyj /api/v2/account/webhooks/:id/rotate-secret.

subscriptions_list_plans

Publiczny katalog usług i cen (LEADS, PRICING, PROCUREMENT). Nie wymaga uwierzytelniania.

meta_list_services

Status wszystkich usług Veritra (czas działania, flagi wycofania).

Przykład curl

Znajdź 5 najlepszych przetargów budowlanych powyżej 1 mln CZK w Pradze:

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

Konfiguracja w Claude Desktop

Dodaj do ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) lub odpowiednika:

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

Po ponownym uruchomieniu Claude Desktop zobaczysz ikonę połączonego serwera MCP w interfejsie. Otwórz rozmowę i zapytaj np. „Jakie są aktualne przetargi budowlane w Pradze powyżej miliona?" — Claude sam wywoła tenders_search.

Inne klienty MCP

Serwer MCP działa przez transport HTTP — kompatybilny z każdym klientem obsługującym JSON-RPC 2.0 przez HTTP. Poniżej przykłady dla najczęściej używanych.

Cursor / Continue / Cline / Zed

Cursor IDE ma wbudowaną obsługę MCP. Edytuj ~/.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

Rozszerzenie VS Code o otwartym kodzie źródłowym. Dodaj 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"
      }
    }
  }
]

Ogólny klient HTTP MCP / wtyczka ChatGPT / niestandardowy LLM

Jeśli Twój klient nie obsługuje natywnie MCP, komunikuj się z API bezpośrednio przez JSON-RPC 2.0. Nagłówki Authorization i X-MRW-Client identyfikują Twoje konto. Pierwszym wywołaniem jest Discovery (tools/list).

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

Limity żądań

Wywołania MCP podlegają tym samym limitom API zarządzania (60/min odczyt, 10/min zapis, 5000/dzień). Po ich przekroczeniu zwracany jest HTTP 429 (kod błędu JSON-RPC -32000).