MCP

Nordvec sert le Model Context Protocol (MCP), de sorte qu'un agent ou un assistant parlant MCP peut découvrir les opérations de votre espace de travail en tant qu'outils et les appeler de manière native, sans document OpenAPI pour les analyser.

Il existe deux serveurs :

Les deux s'exécutent dans l'UE, sur la même infrastructure que le reste de l'API.

Connexion d'un client

Pointez un client MCP vers le serveur de base de connaissances avec votre clé API comme jeton porteur. La plupart des clients acceptent un bloc de configuration comme celui-ci :

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

Le serveur est sans état et utilise HTTP Streamable : chaque message est une POST transportant une requête JSON-RPC, et la réponse est renvoyée dans le corps de la réponse. Il n'y a pas de sessions à maintenir ni de flux initié par le serveur, donc une GET sur l'URL répond 405, et une POST dont le Content-Type n'est pas application/json répond 415 avant que le corps ne soit lu.

Le serveur s'authentifie avec une clé statique porteuse et ne propose pas de découverte OAuth. Un client qui vous permet de définir des en-têtes de requête (agents de codage, extensions d'IDE, l'inspecteur MCP en mode en-tête) se connecte comme indiqué ci-dessus. Un client hébergé ne supportant que le flux d'autorisation OAuth ne peut pas encore se connecter.

Un client qui envoie l'en-tête MCP-Protocol-Version reçoit une réponse sous cette version lorsque le serveur la supporte (2025-06-18 et 2024-11-05), et est refusé avec 400 lorsqu'il ne la supporte pas. Ainsi, une incompatibilité de version est signalée dès le premier message plutôt que sous la forme d'une réponse mal formée ultérieurement.

Outils

Les outils sont dérivés de l'API REST, un outil par opération qu'une clé API peut appeler. Le nom d'un outil est le chemin SDK de l'opération en snake case, avec un segment répétant le précédent supprimé :

tools/list est le catalogue faisant autorité : il n'affiche pour une clé que les outils autorisés par ses portées, et la description de chaque outil indique la portée requise. Le inputSchema d'un outil est le schéma de requête de l'opération et, lorsque l'opération renvoie un objet, son outputSchema est le schéma de réponse. Les résultats comportent structuredContent en plus du texte JSON.

L'appel d'un outil non autorisé par les portées de la clé répond avec une erreur d'outil indiquant FORBIDDEN, le même refus que la route REST, de sorte qu'un client détenant une liste mise en cache d'une autre clé comprend la raison plutôt que de constater l'absence de l'outil.

Limites et erreurs

Un appel d'outil utilise le même compartiment de limitation de débit que l'opération REST correspondante, et chaque autre message utilise son propre compartiment pour le point de terminaison. Les en-têtes X-RateLimit-*, la réponse 429 avec son Retry-After, et l'enveloppe d'erreur sont identiques à ceux de l'API REST. Ainsi, un client qui les gère déjà pour REST les gère également ici.

Un appel d'outil échoué renvoie un résultat d'outil MCP avec isError: true dont le texte est le corps d'erreur REST (code, message, data). Les échecs de validation conservent la même forme fieldErrors que celle renvoyée par l'API REST. Une erreur JSON-RPC est réservée au protocole lui-même : un corps illisible, une méthode inconnue ou une défaillance du serveur.

Les corps de requête sont limités à 1 Mo, la même limite que pour les routes REST.

Un premier échange

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

Le serveur de documentation

Le serveur de documentation à l'adresse /api/mcp ne nécessite pas de clé. Il propose list_guides, get_guide, search_docs et list_connectors, de sorte qu'un agent en train de construire une intégration peut lire ces guides directement. Il est limité en débit par IP, comme les autres points de terminaison publics.