JSON-RPC stdio server

Meerkat exposes a JSON-RPC 2.0 stdio interface for IDE integration, desktop apps, and automation tools. Unlike REST and MCP, the RPC server keeps agents alive between turns for fast multi-turn conversations. The RPC surface is fully runtime-backed:

keep_alive is runtime/session behavior
session/external_event queues runtime-backed external work
committed success is not rewritten to cancellation

Getting started

Start the server

rkat-rpc

The server reads newline-delimited JSON (JSONL) from stdin and writes JSONL to stdout. Each line is a complete JSON-RPC 2.0 message.

Send the handshake

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}

Create a session

{"jsonrpc":"2.0","id":2,"method":"session/create","params":{"prompt":"Hello!"}}

rkat-rpc defaults to a new isolated realm each time. Use --realm <id> to share config/sessions with other surfaces or processes.

Runtime scope

rkat-rpc accepts global scope flags:

rkat-rpc [--realm <id>] [--isolated] [--instance <id>] [--realm-backend <sqlite|redb|jsonl>] [--state-root <path>] [--context-root <path>] [--user-config-root <path>]

--realm: explicit sharing/isolation key
--instance: optional instance metadata
--realm-backend: creation hint only; actual backend is pinned per realm manifest

Method overview

Method	Category	Description
`initialize`	Handshake	Returns server capabilities
`session/create`	Session	Create session and run first turn
`session/list`	Session	List active sessions
`session/read`	Session	Get session state
`session/history`	Session	Get committed session transcript messages
`session/archive`	Session	Remove session from runtime
`session/external_event`	Session	Queue a runtime-backed external event
`session/inject_context`	Session	Append runtime-backed system context to the next turn
`turn/start`	Turn	Start a new turn on existing session
`turn/interrupt`	Turn	Cancel in-flight turn
`runtime/state`	Runtime	Read runtime-backed ingress state
`runtime/accept`	Runtime	Admit external work directly into runtime ingress
`runtime/retire`	Runtime	Retire runtime-backed ingress
`runtime/reset`	Runtime	Reset runtime-backed ingress
`input/state`	Runtime	Read runtime input lifecycle state
`input/list`	Runtime	List runtime input lifecycle records
`mob/prefabs`	Mob	List mob prefab templates (mob feature)
`session/stream_open`	Session	Open a standalone session event stream
`session/stream_close`	Session	Close a standalone session event stream
`mob/create`	Mob	Create a mob from a prefab or definition (mob feature)
`mob/list`	Mob	List mobs (mob feature)
`mob/status`	Mob	Get mob status (mob feature)
`mob/members`	Mob	List mob members (mob feature)
`mob/spawn`	Mob	Spawn a member into a mob (mob feature)
`mob/spawn_many`	Mob	Spawn multiple members into a mob (mob feature)
`mob/retire`	Mob	Retire a mob member (mob feature)
`mob/respawn`	Mob	Respawn a mob member (mob feature)
`mob/wire`	Mob	Wire two mob members for comms (mob feature)
`mob/unwire`	Mob	Remove mob comms wiring (mob feature)
`mob/lifecycle`	Mob	Stop, resume, complete, destroy, or reset a mob (mob feature)
`mob/send`	Mob	Send work to a mob member (mob feature)
`mob/events`	Mob	Read mob events by cursor (mob feature)
`mob/stream_open`	Mob	Open mob or member event stream (mob feature)
`mob/stream_close`	Mob	Close mob or member event stream (mob feature)
`mob/append_system_context`	Mob	Stage system context for a member session (mob feature)
`mob/flows`	Mob	List mob flows (mob feature)
`mob/flow_run`	Mob	Start a mob flow run (mob feature)
`mob/flow_status`	Mob	Get flow run status (mob feature)
`mob/flow_cancel`	Mob	Cancel a flow run (mob feature)
`mob/spawn_helper`	Mob	Spawn a helper member and wait for its result (mob feature)
`mob/fork_helper`	Mob	Fork a helper from an existing member and wait for its result (mob feature)
`mob/force_cancel`	Mob	Force-cancel a member’s active work (mob feature)
`mob/member_status`	Mob	Read canonical status for a specific member (mob feature)
`mob/tools`	Mob	Compatibility/escape-hatch mob tool inventory (mob feature)
`mob/call`	Mob	Compatibility/escape-hatch mob tool call (mob feature)
`comms/send`	Comms	Dispatch a comms command to a session
`comms/peers`	Comms	List discoverable peers (comms feature)
`skills/list`	Skills	List skills with provenance
`skills/inspect`	Skills	Inspect a skill’s full content
`tools/register`	Tools	Register additional callable tools with the runtime
`mcp/add`	MCP	Stage live MCP server addition (mcp feature)
`mcp/remove`	MCP	Stage live MCP server removal (mcp feature)
`mcp/reload`	MCP	Reload one or all MCP servers (mcp feature)
`models/catalog`	Models	List available models with capabilities and provider profiles
`capabilities/get`	Capabilities	Runtime capability report
`config/get`	Config	Read current config
`config/set`	Config	Replace config
`config/patch`	Config	Merge-patch config (RFC 7396)

runtime/* and input/* methods are advertised only when the server is running with the runtime-backed ingress/control-plane surface enabled.

RPC is the canonical typed substrate for the SDKs: use explicit mob/* lifecycle, send, and observation methods from apps. mob/tools and mob/call remain available only as compatibility and escape-hatch surfaces. Inside running sessions, mob capability is still exposed by composing meerkat-mob-mcp (MobMcpState + MobMcpDispatcher) into SessionBuildOptions.external_tools, which provides mob_* tools to the agent.

Protocol

Standard JSON-RPC 2.0 with "jsonrpc": "2.0" on every message. Three message types:

Request (client -> server): has id, method, params
Response (server -> client): has id, result or error
Notification (server -> client): has method, params, no id

Full lifecycle diagram

Client                          Server
  |                                |
  |-- initialize ----------------->|
  |<-- result { capabilities } ----|
  |-- initialized (notification) ->|
  |                                |
  |-- session/create { prompt } -->|
  |<-- session/event (notif) ------|  // AgentEvent stream
  |<-- session/event (notif) ------|
  |<-- result { session_id, ... } -|
  |                                |
  |-- turn/start { session_id } -->|
  |<-- session/event (notif) ------|
  |<-- result { text, usage } -----|
  |                                |
  |-- turn/interrupt { sid } ----->|
  |<-- result {} ------------------|
  |                                |
  |-- session/archive { sid } ---->|
  |<-- result {} ------------------|

Session methods

initialize

Handshake. Returns server capabilities.

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}

server_info.name

string

Server name.

server_info.version

string

Server version.

contract_version

string

Protocol contract version.

methods

array

List of supported method names.

session/create

Create a new session and run the first turn.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "session/create",
  "params": {
    "prompt": "What is Rust?"
  }
}

session/history

Read committed transcript history for an existing session.

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "session/history",
  "params": {
    "session_id": "01936f8a-7b2c-7000-8000-000000000001",
    "offset": 0,
    "limit": 50
  }
}

Returns oldest-to-newest committed messages plus pagination metadata. This method follows the same owner-resolution rules as session/read, including mob-owned session IDs when mob support is enabled. Only prompt is required. All other fields are optional and fall back to config defaults. During execution, session/event notifications are emitted (see Notifications).

Parameter reference

prompt

string

required

The user prompt to send to the agent.

model

string | null

default:"claude-sonnet-4-5"

Model name (e.g. "claude-opus-4-6", "gpt-5.2").

provider

string | null

default:"inferred from model"

Provider name: "anthropic", "openai", "gemini", "other".

max_tokens

u32 | null

default:"config default"

Max tokens per turn.

system_prompt

string | null

default:"null"

Override system prompt.

output_schema

object | null

default:"null"

JSON schema for structured output extraction (wrapper or raw schema).

structured_output_retries

u32

default:"2"

Max retries for structured output validation.

hooks_override

HookRunOverrides | null

default:"null"

Run-scoped hook overrides (entries to add, hook IDs to disable).

enable_builtins

bool

default:"false"

Enable built-in tools (task management, etc.).

enable_shell

bool

default:"false"

Enable shell tool (requires enable_builtins).

enable_memory

bool

default:"false"

Enable semantic memory (memory_search tool + compaction indexing).

keep_alive

bool | null

default:"null"

Keep session alive after turn for comms. null = inherit persisted session intent, true = enable, false = disable. Requires comms_name when enabled.

comms_name

string | null

default:"null"

Agent name for inter-agent communication.

provider_params

object | null

default:"null"

Provider-specific parameters (e.g., thinking config, reasoning effort).

Response fields

session_id

string

UUID of the created session.

text

string

The agent’s response text.

turns

u32

Number of LLM calls made.

tool_calls

u32

Number of tool calls executed.

usage

WireUsage

Token usage breakdown.

structured_output

object | null

Parsed structured output.

schema_warnings

array | null

Schema compatibility warnings.

session/list

List active sessions.

{"jsonrpc":"2.0","id":3,"method":"session/list"}

session/read

Get session state.

{"jsonrpc":"2.0","id":4,"method":"session/read","params":{"session_id":"01936f8a-..."}}

session_id

string

required

Session ID to read.

session/archive

Remove a session from the runtime.

{"jsonrpc":"2.0","id":5,"method":"session/archive","params":{"session_id":"01936f8a-..."}}

session_id

string

required

Session ID to archive.

Turn methods

turn/start

Start a new turn on an existing session.

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "turn/start",
  "params": {
    "session_id": "01936f8a-...",
    "prompt": "Can you explain ownership?",
    "skill_references": ["rust-patterns/ownership"]
  }
}

Returns the same result shape as session/create. Fails with error code -32001 (SESSION_BUSY) if a turn is already in progress.

session_id

string

required

Session ID to continue.

prompt

string

required

The follow-up prompt.

model

string | null

default:"from session"

Model override for this turn. On pending (deferred) sessions this sets the model before materialization. On materialized sessions this hot-swaps the LLM client for the remainder of the session.

provider

string | null

default:"from session"

Provider override (e.g. "anthropic", "openai", "gemini"). Typically inferred from model.

provider_params

object | null

default:"from session"

Provider-specific parameters (e.g. {"thinking_budget": 10000}). Applied alongside model/provider override.

max_tokens

u32 | null

default:"from session"

Max tokens override.

skill_references

string[] | null

Skill IDs to resolve and inject for this turn.

turn/interrupt

Cancel an in-flight turn. No-op if the session is idle.

{"jsonrpc":"2.0","id":7,"method":"turn/interrupt","params":{"session_id":"01936f8a-..."}}

session_id

string

required

Session ID to interrupt.

Event methods

session/external_event

Queue a runtime-backed external event for an existing session.

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "session/external_event",
  "params": {
    "session_id": "01936f8a-...",
    "payload": {"alert": "build failed", "repo": "main"},
    "source": "ci-pipeline"
  }
}

session_id

string

required

Session ID to admit the external event to.

payload

any JSON

required

Any JSON value. Stored as the runtime external-event payload.

source

string

Optional source label. Defaults to "rpc" and becomes the runtime external-event source.

Error -32603 if runtime admission fails, -32602 if the session locator is invalid. This is a queue-only runtime admission path; it does not create a second direct execution loop.

comms/peers

List discoverable peers from configured TrustedPeers and active in-process registrations. Requires the comms feature.

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "comms/peers",
  "params": {
    "session_id": "01936f8a-..."
  }
}

session_id

string

required

Session ID to query peers for.

skills/list

List all skills with provenance information, including active and shadowed entries.

{"jsonrpc":"2.0","id":12,"method":"skills/list"}

skills

array

List of SkillEntry objects with id, name, description, scope, source, is_active, and optional shadowed_by.

Returns error -32603 if skills are not enabled.

skills/inspect

Inspect a skill’s full content (body).

{
  "jsonrpc": "2.0",
  "id": 13,
  "method": "skills/inspect",
  "params": {
    "id": "task-workflow",
    "source": null
  }
}

string

required

Skill ID to inspect (e.g. "task-workflow", "extraction/email").

source

string | null

default:"null"

Load from a specific named source, bypassing first-wins resolution. Useful for inspecting shadowed skills.

MCP methods

mcp/add

Stage a live MCP server addition for a running session. The server is connected at the next turn boundary.

{
  "jsonrpc": "2.0",
  "id": 14,
  "method": "mcp/add",
  "params": {
    "session_id": "01936f8a-...",
    "server_name": "my-tools",
    "server_config": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@my/mcp-server"]
    },
    "persisted": false
  }
}

session_id

string

required

Session ID to add the server to.

server_name

string

required

Name for the MCP server.

server_config

object

required

MCP server configuration (transport, command, args, url, etc.).

persisted

bool

default:"false"

Whether to also write the server to disk config.

mcp/remove

Stage removal of an MCP server from a running session. Active tool calls drain before the server disconnects at the next turn boundary.

{
  "jsonrpc": "2.0",
  "id": 15,
  "method": "mcp/remove",
  "params": {
    "session_id": "01936f8a-...",
    "server_name": "my-tools",
    "persisted": false
  }
}

session_id

string

required

Session ID to remove the server from.

server_name

string

required

Name of the MCP server to remove.

persisted

bool

default:"false"

Whether to also remove from disk config.

mcp/reload

Reload one or all MCP servers for a running session. Useful after config changes.

{
  "jsonrpc": "2.0",
  "id": 16,
  "method": "mcp/reload",
  "params": {
    "session_id": "01936f8a-...",
    "server_name": "my-tools"
  }
}

session_id

string

required

Session ID to reload servers for.

server_name

string | null

default:"null"

Specific server to reload. If null, reloads all servers.

Models

models/catalog

Return the curated model catalog with provider profiles, capability metadata, and parameter schemas.

{"jsonrpc":"2.0","id":17,"method":"models/catalog"}

The catalog is compiled from meerkat-models at build time. No parameters are required.

contract_version

string

Contract version for the catalog response.

providers

array

List of provider entries, each containing provider, default_model_id, and models.

providers[].models[].profile

object

Model profile with capability flags (supports_temperature, supports_thinking, supports_reasoning) and params_schema.

Capabilities

capabilities/get

Return runtime capabilities with status resolved against config. This lists every capability known to Meerkat with its current status (available, disabled by policy, not compiled, etc.).

{"jsonrpc":"2.0","id":8,"method":"capabilities/get"}

Possible status values:

Status	Shape	Meaning
`Available`	`"Available"`	Compiled in, config-enabled, protocol supports it
`DisabledByPolicy`	`{"DisabledByPolicy": {"description": "..."}}`	Compiled in but disabled by policy
`NotCompiled`	`{"NotCompiled": {"feature": "..."}}`	Feature flag absent at compile time
`NotSupportedByProtocol`	`{"NotSupportedByProtocol": {"reason": "..."}}`	This protocol surface does not support it

Config methods

config/get

Read current realm config envelope.

{"jsonrpc":"2.0","id":9,"method":"config/get"}

config/set

Replace config, optionally using generation CAS.

{
  "jsonrpc":"2.0",
  "id":10,
  "method":"config/set",
  "params":{
    "config": {"agent":{"model":"gpt-5.2"}},
    "expected_generation": 3
  }
}

config/patch

Merge-patch the config (RFC 7396).

{
  "jsonrpc":"2.0",
  "id":11,
  "method":"config/patch",
  "params":{
    "patch":{"agent":{"max_tokens_per_turn":8192}},
    "expected_generation": 4
  }
}

config/set also accepts a direct config object as params for compatibility. In that mode, no CAS check is applied.

Notifications

During turn execution, the server emits session/event notifications containing serialized AgentEvent payloads:

{
  "jsonrpc": "2.0",
  "method": "session/event",
  "params": {
    "session_id": "01936f8a-...",
    "event": {
      "type": "text_delta",
      "delta": "Rust is"
    }
  }
}

Event types match the AgentEvent enum in meerkat-core:

Event	Description
`run_started`	Agent execution began
`run_completed`	Agent run finished
`run_failed`	Agent run failed
`turn_started`	New LLM call within the turn
`text_delta`	Streaming text chunk from LLM
`text_complete`	Full text for this turn
`tool_call_requested`	LLM wants to call a tool
`tool_result_received`	Tool result processed
`turn_completed`	LLM call finished
`tool_execution_started`	Tool dispatch began
`tool_execution_completed`	Tool returned a result
`tool_execution_timed_out`	Tool exceeded timeout
`compaction_started`	Context compaction began
`compaction_completed`	Compaction finished
`compaction_failed`	Compaction failed
`budget_warning`	Approaching resource limits
`retrying`	Retrying after transient error
`hook_started`	Hook execution began
`hook_completed`	Hook finished
`hook_failed`	Hook execution failed
`hook_denied`	Hook blocked operation
`hook_rewrite_applied`	Hook rewrote content
`hook_patch_published`	Hook published a patch
`skills_resolved`	Skills loaded for turn
`skill_resolution_failed`	Skill resolution failed
`tool_config_changed`	Tool visibility or MCP config changed
`interaction_complete`	Interaction-scoped stream completed
`interaction_failed`	Interaction-scoped stream failed
`stream_truncated`	Backpressure dropped intermediate events

session/stream_event notifications

When a session event stream is open (via session/stream_open), the server emits session/stream_event notifications. The notification payload mirrors session/event, but is scoped to the explicit stream handle.

{
  "jsonrpc": "2.0",
  "method": "session/stream_event",
  "params": {
    "stream_id": "550e8400-e29b-41d4-a716-446655440000",
    "sequence": 1,
    "session_id": "sess_123",
    "event": { "...": "..." }
  }
}

mob/stream_event notifications

When a mob event stream is open (via mob/stream_open), the server emits mob/stream_event notifications. Requires the mob feature.

{
  "jsonrpc": "2.0",
  "method": "mob/stream_event",
  "params": {
    "stream_id": "550e8400-e29b-41d4-a716-446655440000",
    "sequence": 1,
    "event": { "...": "..." }
  }
}

For mob-wide streams the event is an AttributedEvent (source + profile + envelope). For per-member streams the event is the raw EventEnvelope<AgentEvent>.

Error codes

Standard JSON-RPC codes plus Meerkat-specific application codes:

Code	Name	Description
-32700	Parse error	Invalid JSON
-32600	Invalid request	Not a valid JSON-RPC request
-32601	Method not found	Unknown method
-32602	Invalid params	Missing or invalid parameters
-32603	Internal error	Server error
-32001	Session not found	Session ID does not exist
-32002	Session busy	Turn already in progress
-32003	Session not running	Session not in running state
-32010	Provider error	LLM provider issue (missing key, auth)
-32011	Budget exhausted	Resource limits reached
-32012	Hook denied	Hook blocked the operation
-32013	Agent error	Internal agent error
-32020	Capability unavailable	Required capability not available
-32021	Skill not found	Requested skill does not exist
-32022	Skill resolution failed	Skill resolution error

Architecture

The RPC server is stateful: agents stay alive between turns. This is the key difference from REST (stateless per-request) and MCP (callback pattern).

Client (IDE, app) <--stdio JSONL--> RpcServer
                                       |
                                  MethodRouter
                                       |
                                  SessionRuntime
                                   /    |    \
                            Session  Session  Session
                             Task    Task     Task
                              |       |        |
                            Agent   Agent    Agent
                         (exclusive ownership)

Each session gets a dedicated tokio task that exclusively owns the Agent. This solves the cancel(&mut self) requirement without mutex. Commands (StartTurn, Interrupt, Shutdown) are sent via channels.

Backpressure: The notification channel is bounded. When the client reads slowly, the agent naturally slows down.

Comparison with other surfaces

	CLI	REST	MCP	RPC
Stateful	No	No	No	Yes
Streaming	stderr	SSE	Optional	JSONL notifications
Multi-session	No	No	No	Yes
Cancellation	Ctrl+C	N/A	N/A	`turn/interrupt`
Bidirectional	No	No (SSE one-way)	Partial	Yes

CLI

APIs

​Getting started

​Runtime scope

​Method overview

​Protocol

​Session methods

​initialize

​session/create

​session/history

​Parameter reference

​Response fields

​session/list

​session/read

​session/archive

​Turn methods

​turn/start

​turn/interrupt

​Event methods

​session/external_event

​comms/peers

​skills/list

​skills/inspect

​MCP methods

​mcp/add

​mcp/remove

​mcp/reload

​Models

​models/catalog

​Capabilities

​capabilities/get

​Config methods

​config/get

​config/set

​config/patch

​Notifications

​session/stream_event notifications

​mob/stream_event notifications

​Error codes

​Architecture

​Comparison with other surfaces

​See also

Getting started

Runtime scope

Method overview

Protocol

Session methods

initialize

session/create

session/history

Parameter reference

Response fields

session/list

session/read

session/archive

Turn methods

turn/start

turn/interrupt

Event methods

session/external_event

comms/peers

skills/list

skills/inspect

MCP methods

mcp/add

mcp/remove

mcp/reload

Models

models/catalog

Capabilities

capabilities/get

Config methods

config/get

config/set

config/patch

Notifications

session/stream_event notifications

mob/stream_event notifications

Error codes

Architecture

Comparison with other surfaces

See also