API reference · API 1.0.0

MCP

Model Context Protocol: every GET operation as a read-only tool.

get /api/v1/mcp

MCP: no server-to-client stream

Operation mcp_get · no authentication

MCP clients open a GET to listen for server-initiated messages. This server sends none, so the answer is 405, which tells a client to go on without a stream.

Responses

  • 405

    Always (method_not_allowed).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 503

    The platform cannot answer right now (unavailable; retry after Retry-After), or API tokens are not configured on it (api_tokens_unconfigured; an operator must act).

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • default

    Problem details (RFC 9457)

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
post /api/v1/mcp

MCP: read-only tools over this API

Operation mcp_post · bearer token

The Model Context Protocol endpoint (Streamable HTTP, stateless, JSON answers only). The body is one JSON-RPC 2.0 message or a batch. Methods: initialize, notifications/initialized, ping, tools/list, tools/call.

Every tool is one GET operation of this API, named by its operation id; its arguments are the operation's path and query parameters. tools/list shows only the tools the caller's permissions allow. A tool call runs the GET through this API with the same credentials, so the answer is exactly what a direct call would get; an error answer is isError: true with the problem details as text. No tool can change anything.

Rate limit: this POST counts as one request and every tools/call in it as one more, so a tool call costs two. An unauthenticated POST is a 401 problem, like every other operation.

Request bodyrequired

application/json
One of:
  1. NameTypeDescription
    id string | integer

    Absent on a notification, which gets no reply.
    jsonrpcrequired string
    one of 2.0
    methodrequired string

    initialize, notifications/initialized, ping, tools/list or tools/call; any other method is JSON-RPC error -32601.
    params object

    For tools/call: {"name": <tool>, "arguments": {...}}.
  2. An array of:
    NameTypeDescription
    id string | integer

    Absent on a notification, which gets no reply.
    jsonrpcrequired string
    one of 2.0
    methodrequired string

    initialize, notifications/initialized, ping, tools/list or tools/call; any other method is JSON-RPC error -32601.
    params object

    For tools/call: {"name": <tool>, "arguments": {...}}.

Responses

  • 200

    The JSON-RPC reply, or an array of replies for a batch.

    application/json → inline schema
    Show schema
    One of:
    1. NameTypeDescription
      error object
      NameTypeDescription
      coderequired integer
      data any
      messagerequired string
      idrequired string | integer | null
      jsonrpcrequired string
      one of 2.0
      result object
    2. An array of:
      NameTypeDescription
      error object
      NameTypeDescription
      coderequired integer
      data any
      messagerequired string
      idrequired string | integer | null
      jsonrpcrequired string
      one of 2.0
      result object
    Headers: X-Request-ID
  • 202

    Only notifications were sent: nothing to reply.

    Headers: X-Request-ID
  • 400

    The body is not JSON (JSON-RPC error -32700) or not a JSON-RPC message (-32600).

    application/json → inline schema
    Show schema
    NameTypeDescription
    error object
    NameTypeDescription
    coderequired integer
    data any
    messagerequired string
    idrequired string | integer | null
    jsonrpcrequired string
    one of 2.0
    result object
    Headers: X-Request-ID
  • 401

    Not authenticated: no Authorization: Bearer header (not_authenticated), or the credential is refused (token_invalid, token_expired, token_revoked, principal_disabled, token_ip_not_allowed).

    application/jsonapplication/problem+json → Problem
    Headers: WWW-Authenticate, X-Request-ID
  • 403

    The caller lacks a permission the operation needs (forbidden; required lists the keys, any one of which would do), or the licence refuses a change (licence_locked, licence_restricted, licence_required, with state and remedy; never retry a licence_* code).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 429

    More than 600 requests in a minute with this token (rate_limited), or the first request with this Idempotency-Key is still running (idempotency_request_in_progress). Retry after Retry-After.

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • 503

    The platform cannot answer right now (unavailable; retry after Retry-After), or API tokens are not configured on it (api_tokens_unconfigured; an operator must act).

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • default

    Problem details (RFC 9457)

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
delete /api/v1/mcp

MCP: end a session

Operation mcp_delete · bearer token

The server is stateless and issues no session id: there is nothing to end, and the answer is always 204.

Responses

  • 204

    Nothing to end: the server keeps no session.

    Headers: X-Request-ID
  • 401

    Not authenticated: no Authorization: Bearer header (not_authenticated), or the credential is refused (token_invalid, token_expired, token_revoked, principal_disabled, token_ip_not_allowed).

    application/jsonapplication/problem+json → Problem
    Headers: WWW-Authenticate, X-Request-ID
  • 403

    The caller lacks a permission the operation needs (forbidden; required lists the keys, any one of which would do), or the licence refuses a change (licence_locked, licence_restricted, licence_required, with state and remedy; never retry a licence_* code).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 429

    More than 600 requests in a minute with this token (rate_limited), or the first request with this Idempotency-Key is still running (idempotency_request_in_progress). Retry after Retry-After.

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • 503

    The platform cannot answer right now (unavailable; retry after Retry-After), or API tokens are not configured on it (api_tokens_unconfigured; an operator must act).

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • default

    Problem details (RFC 9457)

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID

Rendered from openapi-v1.json, platform release 1.0.187. Your installation serves the contract of its own version at /api/v1/openapi.json.