MCP

Nordvec implementeert het Model Context Protocol (MCP), dus een agent of assistent die MCP spreekt, kan de operaties van jouw workspace ontdekken als tools en deze native aanroepen, zonder een OpenAPI-document om over na te denken.

Er zijn twee servers:

Beide draaien in de EU, op dezelfde infrastructuur als de rest van de API.

Een client verbinden

Wijs een MCP-client naar de kennisbankserver met jouw API-sleutel als bearer token. De meeste clients accepteren een configuratieblok zoals dit:

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

De server is stateless Streamable HTTP: elk bericht is één POST met één JSON-RPC-verzoek, en het antwoord komt terug in de response body. Er zijn geen sessies om te onderhouden en geen server-geïnitieerde stream, dus een GET op de URL antwoordt met 405, en een POST waarvan de Content-Type niet application/json is, antwoordt met 415 voordat de body wordt gelezen.

De server authenticeert met een statische bearer key en biedt geen OAuth-discovery. Een client waarmee je request headers kunt instellen (codeeragents, IDE-extensies, de MCP Inspector in header-modus) verbindt zoals hierboven getoond; een gehoste client die alleen de OAuth-authorization flow ondersteunt, kan nog niet verbinden.

Een client die de MCP-Protocol-Version header verstuurt, krijgt een antwoord onder die versie als de server deze ondersteunt (2025-06-18 en 2024-11-05) en wordt geweigerd met 400 als dat niet het geval is, zodat een versieconflict al bij het eerste bericht wordt gemeld in plaats van later als een onjuist antwoord.

Tools

De tools zijn afgeleid van de REST API, één tool per operatie die een API-sleutel mag aanroepen. De naam van een tool is het SDK-pad van de operatie in snake case, waarbij een segment dat het voorgaande herhaalt, wordt weggelaten:

tools/list is de autoritatieve catalogus: deze toont een sleutel alleen de tools die de scopes ervan toestaan, en de beschrijving van elke tool vermeldt de scope die vereist is. De inputSchema van een tool is het request-schema van de operatie en, als de operatie een object retourneert, is de outputSchema ervan het response-schema en bevatten resultaten structuredContent naast de JSON-tekst.

Het aanroepen van een tool die de scopes van de sleutel niet toestaan, resulteert in een tool-fout die FORBIDDEN vermeldt, dezelfde weigering als de REST-route geeft. Zo leert een client met een gecachte lijst van een andere sleutel waarom de tool ontbreekt, in plaats van alleen dat deze ontbreekt.

Limieten en fouten

Een tool-aanroep gebruikt dezelfde rate-limit bucket als de corresponderende REST-operatie, en elk ander bericht op het endpoint gebruikt een eigen bucket. De X-RateLimit-* headers, het 429 antwoord met zijn Retry-After, en de foutenvelop zijn hetzelfde als bij de REST API, dus een client die deze al afhandelt voor REST, doet dat hier ook.

Een mislukte tool-aanroep retourneert een MCP-toolresultaat met isError: true waarvan de tekst het REST-foutlichaam is (code, message, data); validatiefouten hebben dezelfde fieldErrors vorm als de REST API retourneert. Een JSON-RPC-fout is gereserveerd voor het protocol zelf: een onleesbare body, een onbekende methode of een serverfout.

Request bodies zijn beperkt tot 1 MB, dezelfde limiet als de REST-routes.

Een eerste uitwisseling

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

De documentatieserver

De documentatieserver op /api/mcp heeft geen sleutel nodig. Deze biedt list_guides, get_guide, search_docs en list_connectors, zodat een agent die een integratie bouwt, deze handleidingen direct kan lezen. Deze is, net als de andere publieke endpoints, rate limited per IP.