MCP

Nordvec unterstützt das Model Context Protocol (MCP). Ein Agent oder Assistent, der MCP spricht, kann die Operationen deines Workspace als Tools entdecken und sie nativ aufrufen – ohne ein OpenAPI-Dokument zum Analysieren.

Es gibt zwei Server:

Beide laufen in der EU auf derselben Infrastruktur wie der Rest der API.

Einen Client verbinden

Richte einen MCP-Client auf den Wissensdatenbank-Server mit deinem API-Schlüssel als Bearer-Token aus. Die meisten Clients akzeptieren einen Konfigurationsblock wie diesen:

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

Der Server ist zustandsloses Streamable HTTP: Jede Nachricht besteht aus einem POST, das eine JSON-RPC-Anfrage enthält, und die Antwort kommt im Antwortbody zurück. Es gibt keine Sitzungen zu verwalten und keinen serverseitigen Stream. Ein GET in der URL antwortet mit 405, und ein POST, dessen Content-Type nicht application/json ist, antwortet mit 415, bevor der Body gelesen wird.

Der Server authentifiziert sich mit einem statischen Bearer-Key und bietet keine OAuth-Discovery. Ein Client, der dir das Setzen von Request-Headern erlaubt (Code-Agenten, IDE-Erweiterungen, der MCP-Inspector im Header-Modus), verbindet sich wie oben gezeigt. Ein gehosteter Client, der nur den OAuth-Autorisierungsflow unterstützt, kann sich derzeit nicht verbinden.

Ein Client, der den MCP-Protocol-Version-Header sendet, erhält eine Antwort unter dieser Version, wenn der Server sie unterstützt (2025-06-18 und 2024-11-05). Andernfalls wird die Anfrage mit 400 abgelehnt. So wird eine Versionsinkompatibilität bereits bei der ersten Nachricht gemeldet, statt später als fehlerhafte Antwort.

Tools

Die Tools leiten sich von der REST-API ab – ein Tool pro Operation, die ein API-Schlüssel aufrufen darf. Der Name eines Tools ist der SDK-Pfad der Operation in Snake-Case, wobei ein Segment, das sich wiederholt, weggelassen wird:

tools/list ist der maßgebliche Katalog: Er zeigt nur die Tools an, die die Berechtigungen des Schlüssels zulassen. Die Beschreibung jedes Tools nennt die erforderliche Berechtigung. Das inputSchema eines Tools ist das Anfrageschema der Operation. Wenn die Operation ein Objekt zurückgibt, ist das outputSchema das Antwortschema, und die Ergebnisse enthalten structuredContent neben dem JSON-Text.

Ein Aufruf eines Tools, das die Berechtigungen des Schlüssels nicht zulassen, antwortet mit einem Tool-Fehler, der FORBIDDEN nennt – dieselbe Ablehnung wie bei der REST-Route. So erfährt ein Client mit einem zwischengespeicherten Listing von einem anderen Schlüssel, warum das Tool fehlt, statt nur, dass es nicht vorhanden ist.

Limits und Fehler

Ein Tool-Aufruf verbraucht denselben Rate-Limit-Bucket wie die entsprechende REST-Operation, und jede andere Nachricht auf dem Endpunkt hat ihren eigenen Bucket. Die X-RateLimit-*-Header, die 429-Antwort mit ihrem Retry-After und das Fehlerformat sind dieselben wie bei der REST-API. Ein Client, der sie bereits für REST verarbeitet, kann sie hier ebenfalls nutzen.

Ein fehlgeschlagener Tool-Aufruf gibt ein MCP-Tool-Ergebnis mit isError: true zurück, dessen Text der REST-Fehlerbody ist (code, message, data). Validierungsfehler haben dieselbe fieldErrors-Struktur wie bei der REST-API. Ein JSON-RPC-Fehler ist für das Protokoll selbst reserviert: ein nicht analysierbarer Body, eine unbekannte Methode oder ein Serverfehler.

Anfragebodies sind auf 1 MB begrenzt – dieselbe Grenze wie bei den REST-Routen.

Ein erster Austausch

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

Der Dokumentationsserver

Der Dokumentationsserver unter /api/mcp benötigt keinen Schlüssel. Er bietet list_guides, get_guide, search_docs und list_connectors an, sodass ein Agent, der eine Integration erstellt, diese Anleitungen direkt lesen kann. Er ist wie die anderen öffentlichen Endpunkte pro IP rate-limitiert.