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
| Property | Value |
|---|---|
| Path | /api/v1/mcp |
| Transport | Streamable HTTP, stateless: one POST per JSON-RPC 2.0 request, one JSON response |
| Protocol versions | 2025-06-18 and 2025-03-26 |
| Methods | initialize, ping, tools/list and tools/call |
| Authentication | Bearer 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.
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"}'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,getBriefandgetDossier. - Inputs are the operation's path and query parameters, plus a
lensobject withasOf,revision,window,themes,regionsandactorsfor lens-scoped operations. Extra properties, wrong types andnullwhere 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: trueand 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.