MCP

Nordvec understøtter Model Context Protocol (MCP), så en agent eller assistent, der taler MCP, kan opdage dine arbejdsområdes operationer som værktøjer og kalde dem naturligt uden et OpenAPI-dokument at resonnere over.

Der er to servere:

Begge kører i EU på samme infrastruktur som resten af API'et.

Tilslutning af en klient

Peg en MCP-klient mod vidensbaseserveren med din API-nøgle som bearer-token. De fleste klienter tager en konfigurationsblok som denne:

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

Serveren er stateless Streamable HTTP: hvert meddelelse er én POST, der bærer én JSON-RPC-anmodning, og svaret kommer tilbage i response-body. Der er ingen sessioner at vedligeholde, og ingen serverinitieret stream, så et GET på URL'en besvarer 405, og et POST, hvis Content-Type ikke er application/json, besvarer 415, før body læses.

Serveren autentificerer med en statisk bearer-nøgle og tilbyder ikke OAuth-discovery. En klient, der lader dig sætte request-headers (kodningsagenter, IDE-udvidelser, MCP Inspector i header-tilstand), tilsluttes som vist ovenfor. En hosted klient, der kun understøtter OAuth-authorization-flow, kan endnu ikke tilsluttes.

En klient, der sender MCP-Protocol-Version-headeren, besvares under den version, når serveren understøtter den (2025-06-18 og 2024-11-05), og afvises med 400, når den ikke gør, så en versionskonflikt rapporteres ved første meddelelse i stedet for som et misdannet svar senere.

Værktøjer

Værktøjerne er afledt af REST API'et, ét værktøj pr. operation, som en API-nøgle må kalde. Et værktøjs navn er operationens SDK-sti i snake case, hvor et segment, der gentager det foregående, fjernes:

tools/list er det autoritative katalog: det viser kun en nøgle de værktøjer, som dens scopes tillader, og hvert værktøjs beskrivelse angiver det scope, det kræver. Et værktøjs inputSchema er operationens request-schema, og hvor operationen returnerer et objekt, er dens outputSchema response-schemaet, og resultater indeholder structuredContent sammen med JSON-teksten.

Et kald til et værktøj, som nøglens scopes ikke tillader, besvares med en værktøjsfejl, der nævner FORBIDDEN, samme afvisning som REST-ruten giver, så en klient med et cachelagret katalog fra en anden nøgle forstår hvorfor, i stedet for blot at erfare, at værktøjet mangler.

Grænser og fejl

Et værktøjskald trækker på samme rate-limit-bucket som den tilsvarende REST-operation, og alle andre meddelelser på endpointens egen bucket. X-RateLimit-*-headers, 429-svaret med dets Retry-After og fejlkonvolutten er de samme som i REST API'et, så en klient, der allerede håndterer dem for REST, håndterer dem her.

Et mislykket værktøjskald returnerer et MCP-værktøjsresultat med isError: true, hvis tekst er REST-fejlbody (code, message, data). Valideringsfejl har samme fieldErrors-form som REST API'et returnerer. En JSON-RPC-fejl er forbeholdt selve protokollen: en ufortolkelig body, en ukendt metode eller en serverfejl.

Request-bodies er begrænset til 1 MB, samme grænse som REST-ruterne.

En første udveksling

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

Dokumentationsserveren

Dokumentationsserveren på /api/mcp kræver ingen nøgle. Den tilbyder list_guides, get_guide, search_docs og list_connectors, så en agent, der bygger en integration, kan læse disse vejledninger direkte. Den er rate-begrænset pr. IP ligesom de andre offentlige endpoints.