Rensei docs
API ReferenceM C P

BYOA MCP facade (JSON-RPC 2.0)

Stateless Streamable-HTTP JSON-RPC 2.0 facade for Bring-Your-Own-Agent (BYOA) hosts. Lets any MCP-capable host dispatch autonomous Rensei agents, poll for audit receipts, and list installed BYOA workflows. There is no server-held session; each request authenticates with an rsk API key, a requester-registration-bound OAuth agent token, a WorkOS user token, or a browser session. Supported methods: - `initialize` - protocol handshake; advertises the `tools` capability and `serverInfo` `{ name: "rensei-byoa-mcp", version: "0.1.0" }`. - `notifications/initialized` - client readiness signal; no response (202). - `tools/list` - lists the three BYOA tools. - `tools/call` - invokes a tool by name with arguments. Tools (each result is JSON-stringified into `result.content[0].text`): - `dispatch` `{ project, goal, workType? }` returns `{ instanceId, sessionId, receiptUrl, streamUrl }`. - `get_receipt` `{ instanceId }` returns `{ receipt }` (assembled v1 dispatch receipt). - `list_workflows` `{}` returns `{ workflows: [{ id, projectId, templateSlug, status, workType }] }`. The credential must carry `dispatch:invoke` (or `*` for an rsk key). REG-10 is request-global and conditional: a registration with a public key signs the exact entire raw JSON-RPC body, including a complete batch array. A strict registration without a public key returns 403. Unbound rsk keys, user tokens, browser sessions, and light registrations without a public key do not sign. Error model: transport/auth failures return literal HTTP statuses (401 missing/invalid credential or signature, 403 missing scope or strict registration misconfiguration, 429 rate limit with `Retry-After`, 503 auth backend stalled past its budget - safe to retry). Tool-level denials and validation errors are returned as a JSON-RPC error object inside an HTTP 200 body - they do NOT surface as HTTP 4xx. JSON-RPC error codes: - `-32700` Parse error - `-32600` Invalid request - `-32601` Method / tool not found - `-32602` Invalid params - `-32603` Internal error - `-32003` Rensei auth-denied (project scope, allowlist, or Cedar policy) - `-32005` Rate limited

POST
/api/cli/mcp

Authorization

headerAuthorizationBearer <rsk_live_*>

Rensei API key presented as Authorization: Bearer rsk_live_. Required API-key scopes are recorded per operation in x-rensei-required-scopes.

Header Parameters

X-Rensei-Project?string

Project slug or id selecting the request's verified home project. Credential projectIds and requester-registration allowedProjectIds are independent ceilings: null is unrestricted and every array is exact, including [] as deny-all. For an org-wide credential plus org-wide requester registration, or a role-checked user, the A2A capability uses the header only as the durable home mailbox while discovery and recipient selection may span sibling projects permitted by Cedar; each message remains stored under one exact resolved project.

Length1 <= length
X-Rensei-Request-Signature?string

Conditionally required: standard base64 of the 64-byte Ed25519 signature over the exact canonical envelope UTF-8 bytes.

Match^[A-Za-z0-9+/]{86}==$
X-Rensei-Request-Timestamp?string

Conditionally required: canonical base-10 integer Unix seconds signed in the envelope; accepted within the inclusive +/-300 second window.

Match^(0|[1-9][0-9]*)$
X-Rensei-Request-Nonce?string

Conditionally required: non-empty opaque per-request nonce signed in the envelope. Replay rejection is best-effort while the Redis replay cache is available.

Length1 <= length

Request Body

application/json
  1. body
jsonrpc*"2.0"
Value in"2.0"
id?string|integer|null
method*string
Value in"initialize""notifications/initialized""tools/list""tools/call"
params?

Response Body

JSON-RPC response (or array for batch). Tool-level errors are returned here as a JSON-RPC error object inside a 200.

application/json
  1. response
jsonrpc*"2.0"
Value in"2.0"
id*string|integer|null
result?unknown

Present on success.

error?
Example Request
curl -X POST 'https://app.rensei.ai/api/cli/mcp' \  -H 'Content-Type: application/json' \  -d '{  "jsonrpc": "2.0",  "method": "initialize"}'
Example Response
{  "jsonrpc": "2.0",  "id": "string",  "result": null,  "error": {    "code": 0,    "message": "string",    "data": null  }}

Store a browser web-push subscription for the authenticated user.

Persists a W3C PushSubscription as a per-user web-push device token. Scoped to the authenticated user; a credential with no user identity is rejected.

Per-session MCP tool surface (initialize, tools/list, tools/call) over JSON-RPC.

Per-session MCP tool surface (initialize, tools/list, tools/call) over JSON-RPC. - Rensei REST API operation reference.