Docs
Model Context Protocol

Model Context Protocol

Connect AI agents to the read operations: transport, protocol versions, authentication, tools and results.

The Model Context Protocol endpoint offers the read operations of the API as tools, for AI agents and clients that speak the protocol instead of REST. Agents use the same credentials as the API and receive the same answers, so a number an agent cites is the number the workbench shows.

The endpoint

PropertyValue
Path/api/v1/mcp
TransportStreamable HTTP, stateless: one POST per JSON-RPC 2.0 request, one JSON response
Protocol versions2025-06-18 and 2025-03-26
Methodsinitialize, ping, tools/list and tools/call
AuthenticationBearer access tokens with the read capability, as for the API

There are no sessions and no server-sent event streams: GET and DELETE answer 405. initialize answers with the requested protocol version when it is supported, and with 2025-06-18 otherwise. A request whose MCP-Protocol-Version header names another version is refused with 400. Batched messages are not supported, and notifications receive 202 without a body.

Connecting a client

Register the endpoint in your MCP client as a remote server over Streamable HTTP, with the URL $PRAXIS_URL/api/v1/mcp and the header Authorization: Bearer followed by an access token. Every request carries the token, so give the client a way to refresh it, as tokens live for minutes.

Shell
curl "$PRAXIS_URL/api/v1/mcp" \
  -H "Authorization: Bearer $PRAXIS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
Shell
curl "$PRAXIS_URL/api/v1/mcp" \
  -H "Authorization: Bearer $PRAXIS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "getDossier",
      "arguments": { "id": "irn", "lens": { "asOf": "2026-06-30" } }
    }
  }'

Tools

The tools are every read operation of the API that uses GET, the scenario lab included. Synchronization is not a tool, and nothing a tool does changes data. tools/list returns the current set.

  • Names and descriptions are the operation IDs, summaries and descriptions of the OpenAPI document, such as getView, getBrief and getDossier.
  • Inputs are the operation's path and query parameters, plus a lens object with asOf, revision, window, themes, regions and actors for lens-scoped operations. Extra properties, wrong types and null where it is not allowed are refused; arguments are never coerced.
  • Annotations mark every tool read-only, non-destructive and closed-world.

Each call is replayed through the API operation itself, with the caller's credentials, origin and request ID, so validation, authorization and problems are exactly those of the REST operation.

Results

  • A successful call returns the operation's response both as text and as structuredContent.
  • Briefs and dossiers called with format: "markdown" return their Markdown as text.
  • A failed operation returns a tool result with isError: true and the problem's detail.
  • An unknown tool or malformed parameters receive JSON-RPC error -32602, an unsupported method -32601, and an unexpected failure -32603.

Pass lens.asOf and lens.revision in every call whose answer an agent will cite. The answer then carries the revision and methodology release behind it and can be reproduced, as Reproducibility describes.