MCP

Nordvec supporta il Model Context Protocol (MCP), quindi un agente o un assistente che parla MCP può scoprire le operazioni del tuo workspace come strumenti e chiamarle nativamente, senza bisogno di un documento OpenAPI per ragionarci sopra.

Ci sono due server:

Entrambi sono eseguiti nell'UE, su la stessa infrastruttura del resto dell'API.

Collegare un client

Punta un client MCP al server della knowledge base con la tua chiave API come bearer token. La maggior parte dei client accetta un blocco di configurazione come questo:

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

Il server è stateless Streamable HTTP: ogni messaggio è una POST che trasporta una richiesta JSON-RPC, e la risposta arriva nel corpo della risposta. Non ci sono sessioni da mantenere e nessun flusso iniziato dal server, quindi una GET sull'URL risponde con 405, e una POST il cui Content-Type non è application/json risponde con 415 prima che il corpo venga letto.

Il server autentica con una chiave bearer statica e non offre la scoperta OAuth. Un client che ti permette di impostare le intestazioni delle richieste (agenti di codifica, estensioni IDE, l'MCP Inspector in modalità intestazione) si collega come mostrato sopra; un client ospitato che supporta solo il flusso di autorizzazione OAuth non può ancora collegarsi.

Un client che invia l'intestazione MCP-Protocol-Version riceve una risposta per quella versione quando il server la supporta (2025-06-18 e 2024-11-05) e viene rifiutato con 400 quando non la supporta, quindi una discrepanza di versione viene segnalata al primo messaggio piuttosto che come una risposta malformata in seguito.

Strumenti

Gli strumenti sono derivati dall'API REST, uno strumento per ogni operazione che una chiave API può chiamare. Il nome di uno strumento è il percorso SDK dell'operazione in snake case, con un segmento che ripete quello precedente eliminato:

tools/list è il catalogo autorevole: mostra solo gli strumenti che gli scope della chiave ammettono, e la descrizione di ogni strumento indica lo scope richiesto. Lo inputSchema di uno strumento è lo schema della richiesta dell'operazione e, quando l'operazione restituisce un oggetto, il suo outputSchema è lo schema della risposta e i risultati portano structuredContent insieme al testo JSON.

Chiamare uno strumento che gli scope della chiave non ammettono risponde con un errore dello strumento che nomina FORBIDDEN, lo stesso rifiuto che dà il percorso REST, quindi un client che tiene una lista memorizzata da un'altra chiave apprende il motivo piuttosto che semplicemente che lo strumento manca.

Limiti ed errori

Una chiamata a uno strumento attinge dallo stesso bucket di limitazione della frequenza dell'operazione REST corrispondente, e ogni altro messaggio sull'endpoint dal proprio bucket. Le intestazioni X-RateLimit-*, la risposta 429 con il suo Retry-After, e la struttura dell'errore sono le stesse dell'API REST, quindi un client che già le gestisce per REST le gestisce anche qui.

Una chiamata a uno strumento fallita restituisce un risultato dello strumento MCP con isError: true il cui testo è il corpo dell'errore REST (code, message, data); i fallimenti di validazione portano la stessa forma fieldErrors che restituisce l'API REST. Un errore JSON-RPC è riservato al protocollo stesso: un corpo non analizzabile, un metodo sconosciuto o un guasto del server.

I corpi delle richieste sono limitati a 1 MB, lo stesso limite delle rotte REST.

Un primo scambio

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

Il server di documentazione

Il server di documentazione su /api/mcp non richiede alcuna chiave. Offre list_guides, get_guide, search_docs e list_connectors, quindi un agente che sta costruendo un'integrazione può leggere queste guide direttamente. È limitato in frequenza per IP come gli altri endpoint pubblici.