MCP

Nordvec serves the Model Context Protocol (MCP), so an agent or an assistant that speaks MCP can discover your workspace's operations as tools and call them natively, without an OpenAPI document to reason about.

There are two servers:

Both run in the EU, on the same infrastructure as the rest of the API.

Connecting a client

Point an MCP client at the knowledge-base server with your API key as a bearer token. Most clients take a configuration block like this one:

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

The server is stateless Streamable HTTP: every message is one POST carrying one JSON-RPC request, and the answer comes back in the response body. There are no sessions to keep and no server-initiated stream, so a GET on the URL answers 405, and a POST whose Content-Type is not application/json answers 415 before the body is read.

The server authenticates with a static bearer key and does not offer OAuth discovery. A client that lets you set request headers (coding agents, IDE extensions, the MCP Inspector in header mode) connects as shown above; a hosted client that only supports the OAuth authorization flow cannot connect yet.

A client that sends the MCP-Protocol-Version header is answered under that version when the server supports it (2025-06-18 and 2024-11-05) and refused with 400 when it does not, so a version mismatch is reported at the first message rather than as a malformed reply later.

Tools

The tools are derived from the REST API, one tool per operation an API key may call. A tool's name is the operation's SDK path in snake case, with a segment that repeats the one before it dropped:

tools/list is the authoritative catalog: it shows a key only the tools its scopes admit, and each tool's description names the scope it requires. A tool's inputSchema is the operation's request schema and, where the operation returns an object, its outputSchema is the response schema and results carry structuredContent alongside the JSON text.

Calling a tool the key's scopes do not admit answers with a tool error naming FORBIDDEN, the same refusal the REST route gives, so a client holding a cached listing from another key learns why rather than that the tool is missing.

Limits and errors

A tool call draws on the same rate-limit bucket as the REST operation it corresponds to, and every other message on the endpoint's own bucket. The X-RateLimit-* headers, the 429 answer with its Retry-After, and the error envelope are the same as on the REST API, so a client that already handles them for REST handles them here.

A failed tool call returns an MCP tool result with isError: true whose text is the REST error body (code, message, data); validation failures carry the same fieldErrors shape the REST API returns. A JSON-RPC error is reserved for the protocol itself: an unparsable body, an unknown method, or a server fault.

Request bodies are capped at 1 MB, the same bound as the REST routes.

A first exchange

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

The documentation server

The documentation server at /api/mcp needs no key. It offers list_guides, get_guide, search_docs and list_connectors, so an agent that is building an integration can read these guides directly. It is rate limited per IP like the other public endpoints.