MCP

Nordvec tilbyr Model Context Protocol (MCP), slik at en agent eller assistent som snakker MCP kan oppdage operasjonene i arbeidsområdet ditt som verktøy og kalle dem direkte, uten et OpenAPI-dokument å resonnere over.

Det er to servere:

Begge kjører i EU, på samme infrastruktur som resten av API-et.

Koble til en klient

Pek en MCP-klient mot kunnskapsbaseserveren med API-nøkkelen din som bearer-token. De fleste klienter tar en konfigurasjonsblokk som denne:

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

Serveren er stateless Streamable HTTP: hver melding er én POST som bærer én JSON-RPC-forespørsel, og svaret kommer tilbake i responsens body. Det er ingen sesjoner å opprettholde og ingen serverinitierte strømmer, så en GET på URL-en svarer med 405, og en POST hvis Content-Type ikke er application/json svarer med 415 før bodyen leses.

Serveren autentiserer med en statisk bearer-nøkkel og tilbyr ikke OAuth-discovery. En klient som lar deg sette forespørselshoder (kodeagenter, IDE-utvidelser, MCP Inspector i hode-modus) kobler til som vist over. En hostet klient som bare støtter OAuth-autoritetsflyt kan ikke koble til ennå.

En klient som sender MCP-Protocol-Version-hodet får svar under den versjonen når serveren støtter den (2025-06-18 og 2024-11-05), og avvises med 400 når den ikke gjør det. Dermed rapporteres en versjonskonflikt ved første melding, i stedet for som en feilformet respons senere.

Verktøy

Verktøyene er avledet fra REST API-et, ett verktøy per operasjon en API-nøkkel kan kalle. Et verktøys navn er operasjonens SDK-sti i snake case, der et segment som gjentar det forrige droppes:

tools/list er den autoritative katalogen: den viser bare nøkkelen de verktøyene omfangene tillater, og hvert verktøys beskrivelse oppgir omfanget det krever. Et verktøys inputSchema er operasjonens forespørselsskjema, og der operasjonen returnerer et objekt, er outputSchema svarskjemaet, og resultatene inneholder structuredContent sammen med JSON-teksten.

Å kalle et verktøy som nøkkelens omfang ikke tillater, svares med en verktøyfeil som oppgir FORBIDDEN – samme avslag som REST-ruten gir. Dermed får en klient som har mellomlagret en liste fra en annen nøkkel vite hvorfor, i stedet for bare at verktøyet mangler.

Begrensninger og feil

Et verktøyoppslag trekker fra samme ratelimit-bøtte som REST-operasjonen det tilsvarer, og alle andre meldinger på endepunktet har sin egen bøtte. X-RateLimit-*-hodene, 429-svaret med Retry-After, og feilkonvolutten er de samme som i REST API-et. Dermed håndterer en klient som allerede støtter dem for REST dem også her.

Et mislykket verktøyoppslag returnerer et MCP-verktøyresultat med isError: true, der teksten er REST-feilens body (code, message, data). Valideringsfeil har samme fieldErrors-form som REST API-et returnerer. En JSON-RPC-feil er reservert for selve protokollen: en uleselig body, en ukjent metode eller en serverfeil.

Forespørselsbodyer er begrenset til 1 MB, samme grense som REST-rutene.

En første utveksling

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

Dokumentasjonsserveren

Dokumentasjonsserveren på /api/mcp trenger ingen nøkkel. Den tilbyr list_guides, get_guide, search_docs og list_connectors, slik at en agent som bygger en integrasjon kan lese disse guidene direkte. Den er ratelimitert per IP, på samme måte som de andre offentlige endepunktene.