Skip to content
Praxrr

MCP Streamable HTTP endpoint

POST
/mcp
curl --request POST \
  --url https://example.com/api/v1/mcp \
  --header 'Content-Type: application/json' \
  --data '{}'

Model Context Protocol (MCP) endpoint over Streamable HTTP, stateless. The request body is a single JSON-RPC 2.0 request or notification: a request returns a single JSON-RPC response, a notification returns 202 with no body. The tool/resource/prompt surface is discovered at runtime via tools/list, resources/list, and prompts/list rather than modeled here.

Read-only: exposes Praxrr’s configuration and observability surface (instances, drift, config health, security posture, PCD databases and resolved entities, sync history, and the redacted feature-aware list_plugins tool) plus a write-free preview_sync. list_plugins exposes no plugin source directory, raw manifest, credential, or mutation handler. Authenticate with an API token (prx_…) carrying the mcp scope (or admin) in the X-Api-Key header; tokens work under AUTH=on, AUTH=oidc, and for remote clients under AUTH=local. There is no OAuth/Bearer support. Disabled (404) when MCP_ENABLED is off.

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
X-Api-Key
string

Praxrr API token (prx_…) with the mcp scope (or admin). Required for non-browser clients under AUTH=on and AUTH=oidc, and for remote clients under AUTH=local.

MCP-Protocol-Version
string

Negotiated MCP protocol version. An unsupported value returns 400.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

A single JSON-RPC 2.0 request or notification object.

object
key
additional properties
any
Examplegenerated
{}

Responses

Section titled “Responses”

200

Section titled “200”

A single JSON-RPC 2.0 response object.

Media typeapplication/json

A single JSON-RPC 2.0 response object (result or error).

object
key
additional properties
any
Examplegenerated
{}

202

Section titled “202”

A JSON-RPC notification was accepted; no response body.

400

Section titled “400”

Unsupported MCP-Protocol-Version header.

Media typeapplication/json
object
error
required

Error message

string
code

Stable machine-readable code present on 5xx responses; error is a fixed user-safe message, raw detail is logged server-side only

string
Allowed values: cleanup_failed library_fetch_failed episodes_fetch_failed releases_fetch_failed
Example
{
  "code": "cleanup_failed"
}

401

Section titled “401”

Unauthenticated (missing, invalid, revoked, or expired API token).

403

Section titled “403”

Rejected cross-origin request (DNS-rebinding defense), or the API token lacks the mcp scope (body { "error": "Forbidden", "requiredScope": "mcp" }). A tool call whose required scope is not granted is a JSON-RPC -32003 error, also returned with 403. The cross-origin rejection has no body.

Media typeapplication/json
One of:

An authenticated API token lacks the scope the requested route requires.

object
error
required

Always Forbidden.

string
requiredScope
required

The API token scope this request requires.

string
Allowed values: read mcp sync:apply admin
Example
{
  "requiredScope": "read"
}

404

Section titled “404”

The MCP endpoint is disabled (MCP_ENABLED is off).

413

Section titled “413”

Request body too large.