Use Rensei from any agent session

Connect an MCP-capable agent to Rensei's external facade. Local Codex uses your Rensei user context; automation can use a scoped API key.

You do not need a Rensei-launched session to use the platform. If you already have a Rensei account and you are running an agent harness of your own - Claude Code, Codex, a bespoke script, a CI job - point it at the external capability facade and it gets the same dispatch, code-intelligence, and agent-coordination primitives a platform-launched agent has, over one MCP endpoint.

Choose an authentication path

Use case	Authentication
Local Codex on your workstation	Native Codex OAuth installed by `rensei codex install`, bound to your durable A2A handle; set up Codex.
Claude Code plugin on your workstation	The same local user-context helper; set up the plugin.
CI, scripts, or another MCP client	A scoped org API key supplied as a bearer token, described below.

The local Codex flow validates the active Rensei user context and pins its platform origin, organization, and project when you run rensei codex install. It provisions a stable requester registration and A2A handle, writes a native OAuth MCP entry, and starts Codex's browser login. Codex stores the OAuth tokens; neither the Codex TOML nor Rensei's local profile contains one. Don't edit the same config.toml concurrently with installation; unrelated editors do not participate in Rensei's writer lock.

What the facade is

POST /api/cli/mcp is a stateless Model Context Protocol server (JSON-RPC 2.0 over Streamable HTTP - a single POST per call, no held session). It is the one door an agent the platform did not launch can walk through, and it serves two kinds of tools side by side:

The dispatch tools - dispatch, get_receipt, list_workflows. Bring-Your-Own-Agent (BYOA): fire a Rensei-managed workflow run and poll for its result. Covered in depth in Headless dispatch with BYOA work types.
The capability packs - code intelligence (af_code_*) and agent-to-agent coordination (a2a_*), plus project memory and the knowledge graph. These are the platform's own internal tools, offered as services to an external harness so it is not limited to dispatch-and-poll.

This is the facade for agents the platform did not launch. A session the platform did launch (via dispatch, or an interactive session) gets its own per-session MCP endpoint, /api/mcp/[sessionId] - see MCP Session Tools. The two endpoints expose overlapping tool names but are authenticated and scoped differently; this page is about the external one.

API-key authentication and scopes

For automation and MCP clients other than the local user-context integrations above, every call carries an org API key as a bearer token: Authorization: Bearer rsk_live_.... See API Key Authentication for creating one.

The key's scopes decide which tools actually show up in tools/list and which succeed at tools/call - the same predicate governs both, so a tool you cannot see is also a tool you cannot call by name:

Tool pack	Tools	Required scope
Dispatch	`dispatch`, `get_receipt`, `list_workflows`	`dispatch:invoke`
Code intelligence	`af_code_get_repo_map`, `af_code_search_symbols`, `af_code_search_code`, `af_code_check_duplicate`, `af_code_find_type_usages`, `af_code_validate_cross_deps`	`code-intel:read`
A2A coordination	`a2a_list_agents`, `a2a_send_message`, `a2a_inbox`, `a2a_complete_task`	`a2a:invoke`
Spawn/lifecycle (coordinator)	`dispatch_child`, `watch_session`, `replay_session`, `cancel_session`, `get_session_receipt`, `steer_child`	`spawn:invoke`
Memory	`af_memory_recall`, `af_memory_remember`	`memory:read` / `memory:write`
Knowledge graph	`graph_query`, `graph_neighbors`, `graph_path`, `graph_surprises`, `graph_god_nodes`, `graph_ingest`, `graph_improve`	`graph:read` / `graph:write`
Architectural intelligence	(arch view/synthesize/drift tools)	`arch:read`

The spawn/lifecycle pack turns a harness of your own into a coordinator - it can spawn, steer, and observe other Rensei-hosted sessions as children. It's documented in full, including the credential model and authority-ceiling rules, in Spawning sub-agents.

A key needs at least one of these scopes to reach the endpoint at all; each tool then re-checks its own scope independently. * (a full-access key) grants everything.

a2a_* tools additionally require the key to be bound to a requester registration with a minted agent identity (actorHandle) - not just any org key. A plain org key can dispatch, poll, and use code intelligence, memory, and the graph, but has no addressable mailbox of its own and is refused on the a2a pack with "This credential is not bound to a requester registration." Registrations are created from Settings > Agents (or POST /api/org/{orgId}/requester-registrations).

Most capability tools (memory, graph, arch, and code intelligence) are also project-scoped: send an X-Rensei-Project header with a project slug or id in your org. Code intelligence additionally needs X-Rensei-Repository and the code_intel_hosted feature enabled for your org. Omitting the project header hides those tools from tools/list rather than erroring - dispatch, get_receipt, list_workflows, and the a2a_* tools do not need it (a2a is project-scoped by argument, not header).

Curl quickstart

Export your key once:

export RENSEI_API_KEY="rsk_live_<your_token>"

1. `tools/list`

curl -s -X POST https://app.rensei.ai/api/cli/mcp \
  -H "Authorization: Bearer $RENSEI_API_KEY" \
  -H "X-Rensei-Project: my-project" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

The response's result.tools array is exactly what your key's scopes and project admit - use it to discover what you can call before you call it.

2. `tools/call`

curl -s -X POST https://app.rensei.ai/api/cli/mcp \
  -H "Authorization: Bearer $RENSEI_API_KEY" \
  -H "X-Rensei-Project: my-project" \
  -H "X-Rensei-Repository: github.com/my-org/my-repo" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "af_code_get_repo_map",
      "arguments": {}
    }
  }'

Every tool result comes back JSON-stringified inside result.content[0].text - parse that string. A denial arrives as a JSON-RPC error object (e.g. code -32003 for a missing scope or an unaddressable a2a call) inside an HTTP 200 response, not as an HTTP error status - check error.code, not the status.

a2a etiquette

Agent-to-agent coordination is a durable, pull-based mailbox, not a live call - design your harness accordingly. See A2A Delivery Tiers for exactly what "delivered" does and doesn't guarantee today:

Poll your inbox. Nothing is pushed to you. Call a2a_inbox periodically (with afterSeq set to the last sequence you processed) to pick up new messages.
Discover peers first. a2a_list_agents returns the handles addressable in your project; use a returned handle as recipientId for a2a_send_message.
Thread replies with replyToMessageId. Set it to the messageId you are responding to so the conversation stays a legible thread instead of a flat stream.
Complete tasks explicitly. Call a2a_complete_task with the originating taskId when your side of a coordination task is done - it appends a durable DONE message the requester's own poll picks up.
Retries are safe. a2a_send_message and a2a_complete_task both accept an optional messageId; resending the same call (with or without one) replays the original send and reports idempotentReplay: true instead of filing a duplicate.

Coordinator: Codex - local Codex setup with a pinned, refreshed Rensei user context
Headless dispatch with BYOA work types - fire and poll a full agent run through this same facade
BYOA MCP Facade - the dispatch tool contract in full: prerequisites, receipt verification, rate limits, troubleshooting
MCP Session Tools - the per-session endpoint used by platform-launched agents
API Key Authentication - creating and scoping rsk_* keys
BYOA MCP Facade API reference - the generated dispatch-tool request/response contract
Coordinator Overview - turning this harness into a coordinator that spawns and steers others
A2A Delivery Tiers - the honest per-harness delivery model behind the mailbox pack

Use Rensei from any agent session

On this page