MCP Session Tools

The MCP endpoint (/api/mcp/[sessionId]) exposes a per-session tool surface to agent subprocesses via the Model Context Protocol (JSON-RPC 2.0 over HTTP POST). It is the primary mechanism through which running agents access platform capabilities - including memory tools, knowledge graph tools, and peer A2A agents.

How it works

When the Rensei daemon dispatches an agent, it writes a per-session MCP configuration file into the agent's working directory pointing at this endpoint. The agent's MCP client speaks Streamable HTTP (JSON-RPC 2.0 POST) to the endpoint throughout the session.

Authentication

POST /api/mcp/{sessionId}
Authorization: Bearer rsk_live_<daemon_key>
Content-Type: application/json

The authenticated org must match the session's organizationId. A mismatch returns 403 Forbidden, preventing cross-org tool access.

Cookie auth is not supported on this endpoint. Daemons and agent subprocesses must use a bearer rsk_* key.

Protocol

The endpoint implements [MCP protocol version 2024-11-05] (Streamable HTTP transport). It handles both single requests and batch arrays.

Server info

{
  "name": "rensei-platform",
  "version": "0.1.0"
}

Supported methods

`initialize`

Protocol handshake. Returns the server's capabilities.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "clientInfo": { "name": "claude-code", "version": "1.0.0" }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": {} },
    "serverInfo": { "name": "rensei-platform", "version": "0.1.0" }
  }
}

`notifications/initialized`

Client readiness notification. The server acknowledges with HTTP 202 No Content (no JSON-RPC response body).

`tools/list`

Returns all tools available for the session. The list is filtered by the session's org and the org's enabled capabilities.

Request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

Response

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "af_memory_recall",
        "description": "Recall relevant observations from agent memory.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": { "type": "string", "description": "Natural-language search phrase or question." },
            "workType": { "type": "string", "description": "Work type - drives observation token budget (e.g. bug_fix, feature, refactor)." }
          },
          "required": ["query", "workType"]
        }
      },
      {
        "name": "af_memory_remember",
        "description": "Store a new observation into agent memory.",
        "inputSchema": { "..." }
      }
    ]
  }
}

`tools/call`

Invoke a named tool. The server injects authoritative tenant context (org, project, session, agent ID) server-side - agents cannot supply these fields directly.

Request

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "af_memory_recall",
    "arguments": {
      "query": "authentication patterns used in this codebase",
      "workType": "bug_fix"
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Previous observations: uses WorkOS AuthKit for SSO; session cookies for browser; rsk_live_* bearer tokens for CLI..."
      }
    ]
  }
}

Built-in tool catalog

Memory tools

Tool	Description
`af_memory_recall`	Recall relevant observations using natural-language query. Merges observation store with knowledge graph triplets when the project has Knowledge Graph memory enabled (per-project; see Knowledge Graph enablement).
`af_memory_remember`	Store a new structured observation into the agent's memory store.

af_memory_recall input schema

Field	Type	Required	Description
`query`	string	Yes	Natural-language search phrase
`workType`	string	Yes	Work type hint for token budget (e.g. `bug_fix`, `feature`, `refactor`, `chore`)

af_memory_remember input schema

Field	Type	Required	Description
`content`	string	Yes	The observation text to store
`type`	string	No	Observation type (e.g. `pattern`, `decision`, `constraint`)
`confidence`	number	No	Confidence score 0-1

Knowledge graph tools

When the project has Knowledge Graph memory enabled, five additional tools are available:

Tool	Description
`graph_query`	Hybrid vector + keyword search over the knowledge graph
`graph_neighbors`	Fetch connected entities up to k hops from a node
`graph_path`	Find shortest path between two entities
`graph_ingest`	Add new triplets to the knowledge graph
`graph_improve`	Update EMA weights on existing triplets (feedback signal)

Knowledge graph tools are gated per project: they appear in tools/list only when the project's memory is enabled and graph is on for that project (isGraphEnabledForProject(orgId, projectId)). There is no org-level graph_engine_enabled flag. Graph-on is OR-semantics - an explicit per-project project_memory_config.graph_enabled=true or the org's plan granting the kg_enabled entitlement. When neither holds (or the project's memory is off), these tools do not appear. See Knowledge Graph enablement.

A2A peer tools

Registered A2A agents are automatically exposed as tools using the naming convention <agentSlug>.<skillId>. For example, a "code-review" agent with a "review" skill becomes code-review-agent.review.

The server-side A2A tool list is built once per org and cached for the process lifetime. Registering or deregistering a peer agent takes effect after the next deployment.

Error codes

Code	Name	Condition
`-32700`	Parse error	Request body is not valid JSON
`-32600`	Invalid request	Missing `jsonrpc` or `method` field
`-32601`	Method not found	Unknown method or unknown tool name
`-32602`	Invalid params	`tools/call` missing `params.name`, or bad argument types
`-32603`	Internal error	Unhandled exception in tool execution
`-32003`	Auth denied	Tool invocation not authorized for this session (A2A peer policy rejection)

Batch requests

The endpoint supports JSON-RPC 2.0 batch requests. Send an array of request objects; receive an array of response objects (notifications with no id are omitted from the response array):

[
  { "jsonrpc": "2.0", "id": 1, "method": "tools/list" },
  { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "af_memory_recall", "arguments": { "query": "auth patterns", "workType": "feature" } } }
]

A2A Agent Card - agent discovery
A2A as MCP tools - peer agents as MCP tools
Memory Observation Store - how observations are stored and retrieved
Knowledge Graph MCP tools - graph tool internals

On this page