MCP

Nordvec obsługuje Model Context Protocol (MCP), więc agent lub asystent, który komunikuje się w MCP, może odkrywać operacje Twojej przestrzeni roboczej jako narzędzia i wywoływać je natywnie, bez dokumentu OpenAPI do analizy.

Dostępne są dwa serwery:

Oba działają w UE, na tej samej infrastrukturze co reszta API.

Podłączanie klienta

Skonfiguruj klienta MCP, aby wskazywał na serwer bazy wiedzy, używając Twojego klucza API jako tokena nośnika. Większość klientów akceptuje blok konfiguracyjny podobny do tego:

{
  "mcpServers": {
    "nordvec": {
      "url": "https://nordvec.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer nv_your_api_key"
      }
    }
  }
}

Serwer jest bezstanowy i obsługuje strumieniowy HTTP: każda wiadomość to jedno POST zawierające jedno żądanie JSON-RPC, a odpowiedź wraca w treści odpowiedzi. Nie ma sesji do utrzymywania ani strumienia inicjowanego przez serwer, więc GET w adresie URL odpowiada 405, a POST, którego Content-Type nie jest application/json, odpowiada 415 przed odczytaniem treści.

Serwer uwierzytelnia za pomocą statycznego klucza nośnika i nie oferuje odkrywania OAuth. Klient, który pozwala ustawić nagłówki żądań (agenty kodujące, rozszerzenia IDE, Inspektor MCP w trybie nagłówków), łączy się jak pokazano powyżej. Klient hostowany, który obsługuje tylko przepływ autoryzacji OAuth, nie może jeszcze się połączyć.

Klient, który wysyła nagłówek MCP-Protocol-Version, otrzymuje odpowiedź w tej wersji, jeśli serwer ją obsługuje (2025-06-18 i 2024-11-05), a jeśli nie, otrzymuje odmowę z 400. Dzięki temu niezgodność wersji jest raportowana przy pierwszej wiadomości, a nie jako nieprawidłowa odpowiedź później.

Narzędzia

Narzędzia są wyprowadzane z API REST, jedno narzędzie na operację, którą może wywołać klucz API. Nazwa narzędzia to ścieżka SDK operacji w formacie snake_case, z pominiętym segmentem powtarzającym poprzedni:

tools/list to autorytatywny katalog: pokazuje klucz tylko te narzędzia, na które pozwalają jego zakresy, a opis każdego narzędzia zawiera nazwę wymaganego zakresu. inputSchema narzędzia to schemat żądania operacji, a jeśli operacja zwraca obiekt, jego outputSchema to schemat odpowiedzi, a wyniki zawierają structuredContent obok tekstu JSON.

Wywołanie narzędzia, na które nie pozwalają zakresy klucza, kończy się błędem narzędzia z nazwą FORBIDDEN, czyli tą samą odmową, którą daje trasa REST. Dzięki temu klient przechowujący buforowaną listę z innego klucza dowiaduje się dlaczego, a nie tylko, że narzędzie jest niedostępne.

Limity i błędy

Wywołanie narzędzia korzysta z tego samego limitu szybkości co odpowiadająca mu operacja REST, a każda inna wiadomość z własnego limitu punktu końcowego. Nagłówki X-RateLimit-*, odpowiedź 429 z Retry-After oraz koperta błędu są takie same jak w API REST, więc klient, który już je obsługuje dla REST, poradzi sobie i tutaj.

Nieudane wywołanie narzędzia zwraca wynik narzędzia MCP z isError: true, którego tekst to treść błędu REST (code, message, data). Błędy walidacji mają taki sam kształt fieldErrors, jaki zwraca API REST. Błąd JSON-RPC jest zarezerwowany dla samego protokołu: nieparsowalna treść, nieznana metoda lub błąd serwera.

Treści żądań są ograniczone do 1 MB, tak samo jak w trasach REST.

Pierwsza wymiana

# Discover the tools your key can call
curl https://nordvec.com/api/v1/mcp \
  -H "Authorization: Bearer $NORDVEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Search the workspace
curl https://nordvec.com/api/v1/mcp \
  -H "Authorization: Bearer $NORDVEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"documents_search","arguments":{"query":"data retention policy"}}}'

Serwer dokumentacji

Serwer dokumentacji pod adresem /api/mcp nie wymaga klucza. Udostępnia list_guides, get_guide, search_docs i list_connectors, więc agent budujący integrację może bezpośrednio czytać te przewodniki. Jest ograniczony szybkością na adres IP, podobnie jak inne publiczne punkty końcowe.