MCP - Meerkat

Model Context Protocol (MCP) is the tool protocol Meerkat uses in two ways: as a client calling external MCP servers for tools, and as a server exposing itself as MCP tools for other clients.

Getting started as a client

Add an MCP server

rkat mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /tmp

Verify it's registered

rkat mcp list

Use it in a session

The agent will automatically discover and use tools from registered MCP servers.

Tool overview (server mode)

The meerkat-mcp-server crate exposes Meerkat as MCP tools that other clients can call. meerkat_run and meerkat_resume keep the same public MCP tool contract, but their execution path is runtime-backed: meerkat_run allocates a session through the shared session service and waits for that admitted turn to finish, and meerkat_resume re-enters the same session_id instead of starting a second surface-local execution loop. The base MCP tool surface below is declared and dispatched in the meerkat-mcp-server crate (crates/meerkat-mcp-server/src/lib.rs), which is the source of truth for tool names and availability.

Tool	Description
`meerkat_run`	Start a new agent session
`meerkat_resume`	Continue a session or provide tool results
`meerkat_help`	Ask Meerkat usage help with the embedded platform skill
`meerkat_read`	Read a session’s state
`meerkat_history`	Read a session’s committed history
`meerkat_sessions`	List sessions in the active realm
`meerkat_blob_get`	Fetch a blob payload by id
`meerkat_interrupt`	Interrupt an in-flight turn
`meerkat_archive`	Archive (remove) a session
`meerkat_config`	Get or update server config
`meerkat_capabilities`	Query runtime capabilities
`meerkat_models_catalog`	List available models with provider profiles and capabilities
`meerkat_skills`	List or inspect available skills
`meerkat_schedule_*` tools	Agent-facing schedule create/get/list/update/pause/resume/delete/occurrences tools
`workgraph_*` tools	Agent-facing WorkGraph create/read/claim/update/link/evidence/close tools
`meerkat_mcp_add`	Stage a live MCP server addition on an active session
`meerkat_mcp_remove`	Stage a live MCP server removal on an active session
`meerkat_mcp_reload`	Stage a live MCP server reload on an active session
`meerkat_event_stream_open`	Open a session-level agent event stream
`meerkat_event_stream_read`	Read the next item from an open event stream
`meerkat_event_stream_close`	Close a previously opened event stream
`meerkat_mob_create`	Create a mob from a typed public definition (mob feature)
`meerkat_mob_list`	List active mobs (mob feature)
`meerkat_mob_status`	Get lifecycle status for one mob (mob feature)
`meerkat_mob_lifecycle`	Apply a lifecycle action to a mob (mob feature)
`meerkat_mob_spawn`	Spawn a member into a mob (mob feature)
`meerkat_mob_spawn_many`	Spawn multiple members into a mob (mob feature)
`meerkat_mob_retire`	Retire a mob member (mob feature)
`meerkat_mob_respawn`	Respawn a mob member with topology restore (mob feature)
`meerkat_mob_wire`	Wire two mob members or an external peer (mob feature)
`meerkat_mob_wire_members_batch`	Wire multiple mob member pairs in one call (mob feature)
`meerkat_mob_unwire`	Remove mob comms wiring (mob feature)
`meerkat_mob_member_send`	Deliver host-owned work to a specific mob member (mob feature)
`meerkat_mob_append_system_context`	Append one ordinary durable ordered System message to a member session (mob feature)
`meerkat_mob_events`	Read mob event history (mob feature)
`meerkat_mob_flows`	List flows defined for a mob (mob feature)
`meerkat_mob_run`	Invoke a mob as a typed callable run (mob feature)
`meerkat_mob_flow_run`	Start a mob flow run (mob feature)
`meerkat_workgraph_flow_launch`	Durably bind a WorkGraph item to an exact Mob Flow attempt before launch (mob feature)
`meerkat_workgraph_flow_reconcile`	Explicitly reconcile a durable WorkGraph Flow binding (mob feature)
`meerkat_workgraph_flow_abandon_uncertain`	CAS-fence an ambiguous Begin-without-run launch, project failure evidence, and make a superseding retry eligible (mob feature)
`meerkat_workgraph_flow_binding_get`	Read one redacted WorkGraph Flow execution binding (mob feature)
`meerkat_workgraph_flow_binding_list`	List bounded redacted WorkGraph Flow execution bindings (mob feature)
`meerkat_mob_flow_status`	Get flow run status (mob feature)
`meerkat_mob_run_result`	Get the typed output envelope for a mob run (mob feature)
`meerkat_mob_flow_cancel`	Cancel a flow run (mob feature)
`meerkat_mob_force_cancel`	Force-cancel a member’s active work (mob feature)
`meerkat_mob_wait_kickoff`	Wait for autonomous kickoff completion (mob feature)
`meerkat_mob_wait_ready`	Wait for mob startup readiness (mob feature)
`meerkat_mob_profile_*` tools	Realm-scoped mob profile create/get/list/update/delete (mob feature)
`meerkat_mob_member_history`	Read a mob member transcript page by identity, local or placed (mob feature)
`meerkat_mob_hosts`	List bound member hosts with capabilities (mob feature)
`meerkat_mob_route_installs`	Read outstanding cross-host route-install obligations (mob feature)
`meerkat_mob_event_stream_open`	Open a mob-level event stream (mob feature)
`meerkat_mob_event_stream_read`	Read the next event from an open mob stream (mob feature)
`meerkat_mob_event_stream_close`	Close a previously opened mob event stream (mob feature)
`meerkat_comms_send`	Send a canonical comms command to a session (comms feature)
`meerkat_comms_peers`	List peers visible to a session (comms feature)

Default rkat-mcp builds are driven by the crate feature set. The base/default tool surface includes core session/config/history/blob/skills tools and schedule and WorkGraph tools. Mob tools appear when the mob feature is compiled in. The WorkGraph Flow tools are advertised only by hosts that also configure a WorkGraph service. Their shared Mob runtime bridge owns reconciliation; MCP is only the transport adapter. Flow status carries a redacted reverse execution-binding reference when the run was launched by the bridge. Public binding views omit activation parameters, idempotency and correlation values, and execution principals.

When the mob feature is enabled, the public MCP host surface uses typed meerkat_mob_* control-plane tools. Inside running sessions, mob capability is still agent-side and comes from composing a mob tools factory into SessionBuildOptions.mob_tools, which provides mob_* tools to the model. Public host MCP surfaces should not re-export that raw dispatcher.

The multi-host console family adds the three observation tools only. Existing meerkat_mob_spawn and meerkat_mob_spawn_many mutations may carry placement for an already-bound host. Host admin (bind_host/revoke_host), grant admin (grant_scopes/revoke_scopes/grants), hard cancel, and member live-channel verbs remain deliberately absent — MCP servers are routinely wired into agent tool contexts, and an LLM-reachable admin mutation would be a privilege-escalation vector. Host/grant/live admin lives on JSON-RPC/SDK plus CLI; hard cancel is JSON-RPC/SDK-only. Unknown tool names fail closed.

resume_from_role is not accepted by meerkat_mob_spawn, spawn-many, helper, or profile tools. Durable member role migration is a one-request trusted-host operation available only to in-process SpawnMemberSpec and the private member-host materialization protocol. It is not an MCP permission or a standing profile setting.

Surface boundaries

The MCP server deliberately does not mirror every operator API:

Domain	MCP exposure
Approvals	None; use JSON-RPC/SDK `approval/*`
Durable jobs and monitors	None; use JSON-RPC/SDK `jobs/*` and `monitors/start`
Blobs	`meerkat_blob_get` fetches a known blob ID
Stable artifact records/downloads	None; use JSON-RPC/SDK `artifact/*`
Live audio/WebRTC channels	None; use JSON-RPC/SDK `live/*`
Multi-host mobs	Placement plus observation only; admin remains RPC/SDK/CLI

Session event streams are bounded live subscriptions. If a consumer falls behind, the stream yields the typed stream_truncated event with a StreamLagged dropped count and then continues with retained events. That is a live-delivery gap, not an EventStore projection result. Built-in realm-backed persistent sessions can feed a separate durable audit projector whose unbounded queue is independent of the UI ring. That projection is asynchronous derived state, so reconcile available replay/snapshot evidence with current session state when completeness matters.

Use MCP servers as tools (client)

CLI configuration (recommended)

Use the rkat mcp commands to manage MCP servers:

# Add a stdio server
rkat mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /tmp

# Add a streamable HTTP server
rkat mcp add api --url https://mcp.example.com/api

# Add a streamable HTTP server with Claude-compatible positional URL syntax
rkat mcp add --transport http remote https://mcp.example.com/api

# Log in when the HTTP server requires OAuth
rkat mcp login remote

# List servers
rkat mcp list

# Remove a server
rkat mcp remove filesystem

Config file format

MCP servers are stored in TOML in two scopes:

Project: .rkat/mcp.toml
User: ~/.rkat/mcp.toml

Project config wins on name collisions.

Config file examples

# Stdio server (local process)
[[servers]]
name = "filesystem"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]

# Stdio server with env
[[servers]]
name = "database"
command = "python"
args = ["-m", "db_mcp_server"]
env = { DATABASE_URL = "${DATABASE_URL}" }

# HTTP server (streamable HTTP is default for URLs)
[[servers]]
name = "remote-api"
url = "https://mcp.example.com/api"
headers = { Authorization = "Bearer ${MCP_API_TOKEN}" }

# OAuth-protected HTTP server. No OAuth schema is persisted here;
# discovery and token storage happen when connecting or running `mcp login`.
[[servers]]
name = "remote-oauth"
url = "https://mcp.example.com/api"

# Legacy SSE server
[[servers]]
name = "legacy-sse"
url = "https://old.example.com/sse"
transport = "sse"

Supported transports: stdio, streamable HTTP (default for URLs), and SSE. Environment variables in config use ${VAR_NAME} syntax.

For OAuth-protected streamable HTTP servers, keep config simple. Add the URL with rkat mcp add, then run rkat mcp login <name> for an explicit browser login, or rkat run "..." --mcp-auth interactive to allow first-use browser auth during an interactive TTY run. Normal runs default to --mcp-auth stored.

Meerkat as an MCP server

Connecting other clients

You can connect any MCP-capable client to a Meerkat MCP server. Run a server process that exposes the meerkat_* tools (stdio or HTTP), then point the client at it.

Claude Code
Codex CLI
Gemini CLI

Claude Code reads MCP servers from a .mcp.json file in your project root. Example stdio config:

{
  "mcpServers": {
    "meerkat": {
      "command": "rkat-mcp",
      "args": [],
      "env": {
        "ANTHROPIC_API_KEY": "your-key"
      }
    }
  }
}

Codex CLI supports MCP servers via a command and also via config. Example:

codex mcp add meerkat --env ANTHROPIC_API_KEY=your-key -- rkat-mcp

You can also configure MCP servers in ~/.codex/config.toml under [mcp_servers.<name>].

Gemini CLI can add MCP servers via CLI or config. Example:

# HTTP/streamable HTTP
gemini mcp add --scope=project --transport=http meerkat https://your-mcp-server.example.com

Or configure in .gemini/settings.json (project-scoped) with an mcpServers map that points to your server URL.

Hosting the MCP server

meerkat-mcp-server is a library crate that provides tool schemas and handlers. For a full public MCP host, serve MeerkatMcpState::advertised_tools_list() from the same state used by the handle_tools_call* entrypoints, or run the bundled rkat-mcp binary. This instance-filtered catalog omits unavailable runtime tools, such as skills when no skill runtime is installed. meerkat_mcp_server::tools_list() is the static composable definition catalog, not the ready-to-serve instance catalog. For a mob-only MCP host, meerkat-mob-mcp exposes public_tools_list() and handle_public_tools_call() for the typed meerkat_mob_* control plane. meerkat-mob-mcp::tools_list() and handle_tools_call() remain the internal agent-side mob_* dispatcher helpers; they are not the public host contract. The bundled rkat-mcp binary supports the complete runtime scope flags:

rkat-mcp [--realm <id>] [--isolated] [--instance <id>] \
  [--realm-backend <sqlite|jsonl|memory>] [--state-root <path>] \
  [--context-root <path>] [--user-config-root <path>] [--expose-paths]

If --realm is omitted, the server creates a new isolated realm by default. --realm-backend is a creation hint only; after the first open, the manifest-pinned backend is authoritative. The bundled binary is stdio-only. If an embedding host publishes these tools over HTTP, that host owns transport authentication, authorization, and encryption; provider auth bindings configure outbound model credentials and do not authenticate inbound MCP callers.

Logging

rkat-mcp writes trace events to stderr only; stdout carries nothing but the MCP JSON channel. The default filter is info, which is what makes the verbose parameter of meerkat_run and meerkat_resume produce output. RUST_LOG replaces the default (RUST_LOG=warn keeps only warnings and errors; a blank value is treated as unset), and a value that does not parse is reported on stderr before the default applies, so an operator’s typo is never swallowed. Clients that capture stderr see these lines; nothing changes on stdout.

Request cancellation

The bundled server accepts MCP’s notifications/cancelled notification. While a tools/call request with JSON-RPC ID 2 is in flight, send:

Client -> server notification

{"jsonrpc":"2.0","method":"notifications/cancelled","params":{"requestId":2}}

requestId must be the original request’s exact ID, preserving its number/string type, not a session ID. This notification has no id and receives no response. It can cancel an uncommitted meerkat_run request before creation has returned a session identity. For example, cancellation before response publication can resolve that original request as:

Server -> client response to the original request

{"jsonrpc":"2.0","id":2,"error":{"code":-32005,"message":"request cancelled before response publish"}}

Cancellation does not roll back committed work: committed success is not rewritten to cancellation. This request lifecycle operation is distinct from meerkat_interrupt, which targets an existing session’s turn. Raw Meerkat JSON-RPC instead uses cancel with request_id; do not interchange those transport spellings.

Event streaming

Push notifications

Set stream: true on meerkat_run or meerkat_resume:

tools/call request

{
  "jsonrpc": "2.0",
  "id": 20,
  "method": "tools/call",
  "params": {
    "name": "meerkat_run",
    "arguments": {"prompt": "Explain Rust ownership", "stream": true}
  }
}

The bundled server emits MCP notifications/message messages while the request runs:

Push notification

{
  "jsonrpc": "2.0",
  "method": "notifications/message",
  "params": {
    "level": "info",
    "data": {
      "source": "meerkat",
      "session_id": "01936f8a-7b2c-7000-8000-000000000001",
      "event": {
        "event_id": "01936f8a-7b2c-7000-8000-000000000010",
        "source": {
          "type": "session",
          "session_id": "01936f8a-7b2c-7000-8000-000000000001"
        },
        "seq": 12,
        "timestamp_ms": 1736937000000,
        "payload": {"type": "text_delta", "delta": "Ownership"}
      }
    }
  }
}

The agent event is a full EventEnvelope<AgentEvent>; inspect params.data.event.payload, not params.data.event.type. Notifications have no request ID and do not replace the final tools/call response. A failure to serialize an event instead emits level: "error" with data.error: "event_serialization_failed" and data.message.

Pull streams: open, read, close

Pull streams are independent tool handles, not push notifications. Invoke these names via tools/call:

Tool	Arguments	Decoded result
`meerkat_event_stream_open`	Required `session_id`	`stream_id`, `session_id`
`meerkat_event_stream_read`	Required `stream_id`; optional `timeout_ms`, `no_timeout`	`stream_id`, `status`, and `event` only for status `event`
`meerkat_event_stream_close`	Required `stream_id`	`stream_id`, `closed` (boolean)
`meerkat_mob_event_stream_open`	Required `mob_id`; optional `member_id`	`stream_id`, `mob_id`, `member_id` (null for mob-wide)
`meerkat_mob_event_stream_read`	Required `stream_id`; optional `timeout_ms`, `no_timeout`	Same read-status wrapper
`meerkat_mob_event_stream_close`	Required `stream_id`	`stream_id`, `closed` (boolean)

The three mob tools require the mob feature. Each pull-tool result wraps its payload as JSON text in result.content[0].text; parse that string once. For example:

{
  "jsonrpc": "2.0",
  "id": 30,
  "method": "tools/call",
  "params": {
    "name": "meerkat_event_stream_open",
    "arguments": {"session_id": "01936f8a-7b2c-7000-8000-000000000001"}
  }
}

{
  "jsonrpc": "2.0",
  "id": 30,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"stream_id\":\"550e8400-e29b-41d4-a716-446655440000\",\"session_id\":\"01936f8a-7b2c-7000-8000-000000000001\"}"
    }]
  }
}

{
  "jsonrpc": "2.0",
  "id": 40,
  "method": "tools/call",
  "params": {
    "name": "meerkat_mob_event_stream_open",
    "arguments": {"mob_id": "review-team", "member_id": "worker-1"}
  }
}

{
  "stream_id": "550e8400-e29b-41d4-a716-446655440001",
  "mob_id": "review-team",
  "member_id": "worker-1"
}

Read with flat timeout fields (there is no nested timeout object):

Read session stream

{
  "jsonrpc": "2.0",
  "id": 31,
  "method": "tools/call",
  "params": {
    "name": "meerkat_event_stream_read",
    "arguments": {
      "stream_id": "550e8400-e29b-41d4-a716-446655440000",
      "timeout_ms": 1000,
      "no_timeout": false
    }
  }
}

timeout_ms is an optional non-negative millisecond count. Omission/null uses the production default of 5000 ms; no_timeout defaults to false. no_timeout: true waits indefinitely and takes precedence even if timeout_ms is also supplied. Mob reads use the same flat fields with meerkat_mob_event_stream_read and the mob stream’s returned ID. The decoded read payload has one of three statuses:

{
  "stream_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "event",
  "event": {
    "event_id": "01936f8a-7b2c-7000-8000-000000000010",
    "source": {
      "type": "session",
      "session_id": "01936f8a-7b2c-7000-8000-000000000001"
    },
    "seq": 12,
    "timestamp_ms": 1736937000000,
    "payload": {"type": "text_delta", "delta": "Ownership"}
  }
}

{"stream_id":"550e8400-e29b-41d4-a716-446655440000","status":"timeout"}

{"stream_id":"550e8400-e29b-41d4-a716-446655440000","status":"closed"}

A timeout leaves the handle open for the next read. Exhaustion returns closed and removes the handle; another read then fails as not found. Session and per-member reads carry an EventEnvelope<AgentEvent> directly under event. Omit member_id to open a mob-wide stream: its events are AttributedEvent values with member attribution and a nested envelope, so the agent payload is at event.envelope.payload instead of event.payload. Close a handle when finished:

{
  "jsonrpc": "2.0",
  "id": 32,
  "method": "tools/call",
  "params": {
    "name": "meerkat_event_stream_close",
    "arguments": {"stream_id": "550e8400-e29b-41d4-a716-446655440000"}
  }
}

{"stream_id":"550e8400-e29b-41d4-a716-446655440000","closed":true}

For a mob handle, use meerkat_mob_event_stream_close with its stream_id. closed: true means this call removed the handle; false means it was already absent. Close results use a boolean, unlike a read’s status: "closed".

Tool reference

meerkat_run

Start a new Meerkat agent session with the given prompt.

{
  "prompt": "Write a haiku about Rust"
}

{
  "prompt": "Analyze this code for bugs",
  "transient_turn_context": "Current host facts regenerated for this turn",
  "system_prompt": "You are a senior code reviewer.",
  "model": "claude-opus-4-8",
  "max_tokens": 4096,
  "provider": "anthropic",
  "output_schema": {
    "type": "object",
    "properties": {
      "bugs": {"type": "array", "items": {"type": "string"}},
      "severity": {"type": "string"}
    },
    "required": ["bugs", "severity"]
  },
  "structured_output_retries": 2,
  "stream": false,
  "verbose": false,
  "tools": [
    {
      "name": "read_file",
      "description": "Read a file from disk",
      "input_schema": {
        "type": "object",
        "properties": {"path": {"type": "string"}},
        "required": ["path"]
      },
      "handler": "callback"
    }
  ],
  "enable_builtins": false,
  "builtin_config": {
    "enable_shell": false,
    "shell_timeout_secs": 30
  },
  "keep_alive": null,
  "comms_name": null,
  "hooks_override": null
}

transient_turn_context is non-empty text; whitespace is significant. It is
retained with the pending runtime input for exact crash retry and projected
only into foreground provider requests for this logical turn. It is not a
System message, is not appended to Session, and is excluded from compaction and
extraction calls.

{
  "content": [{
    "type": "text",
    "text": "{\"content\":[{\"type\":\"text\",\"text\":\"Agent response here\"}],\"session_id\":\"01936f8a-7b2c-7000-8000-000000000001\",\"turns\":1,\"tool_calls\":0,\"structured_output\":null,\"extraction_error\":null,\"schema_warnings\":null,\"skill_diagnostics\":null}"
  }]
}

Parameter reference

string

required

User prompt for the agent.

string | null

default:"null"

Override system prompt.

string | null

default:"config default"

Model name (e.g. "claude-opus-4-8", "gpt-5.5").

u32 | null

default:"config default"

Max tokens per turn.

string | null

default:"inferred"

Explicit MCP override vocabulary: "anthropic", "openai", "gemini", or "other". "self_hosted" is not an accepted explicit token here. Omission/null still permits configured model/binding resolution, including configured self-hosted routes; accepting "other" does not guarantee an operational custom provider.

WireAuthBindingRef | null

default:"null"

Optional structural credential selector, for example {"realm":"prod","binding":"anthropic","profile":"claude_oauth"}. realm and binding are required when supplied; profile is optional. Configure the referenced realm, binding, and auth profile first. Omission/null lets the create resolver select credentials. This is not a colon-delimited CLI string and does not accept server-owned provenance. It is a meerkat_run selector, not a new meerkat_resume field.

object | null

default:"null"

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

u32 | null

default:"null"

Max retries for structured output validation. Omit / null to use the product default on run or inherit the persisted session value on resume.

bool

default:"false"

Stream agent events via notifications/message; see event streaming for the envelope and pull-stream tools.

bool

default:"false"

Enable verbose event logging (server-side).

array

default:"[]"

Tool definitions for the agent (see McpToolDef schema below).

bool | null

default:"null"

Builtins override. Omit / null to use the default on run or inherit the persisted session value on resume.

object | null

default:"null"

Config for builtins (only used when enable_builtins is true).

bool | null

default:"null"

Shell-tools override. Omit / null to use the default on run or inherit the persisted session value on resume.

u64 | null

default:"30"

Default shell command timeout.

bool | null

default:"null"

Keep session alive after turn for comms. On meerkat_run, null/omitted uses the run default (false), true enables, and false explicitly disables. Requires comms_name when enabled.

string | null

default:"null"

Agent name for comms.

HookRunOverrides | null

default:"null"

Run-scoped hook overrides.

McpToolDef schema

string

required

Tool name.

string

required

Tool description.

object

required

JSON Schema for tool input.

string | null

default:"callback"

Handler type ("callback" = result provided via meerkat_resume).

When tools with handler: "callback" are provided and the agent requests a tool call, the response includes pending_tool_calls. The MCP client must execute the tool and provide results via meerkat_resume.

meerkat_resume

Resume an existing runtime-backed session or provide tool results for pending tool calls. The call waits for the resumed turn to complete and returns the same session_id that meerkat_run originally materialized.

{
  "session_id": "01936f8a-7b2c-7000-8000-000000000001",
  "prompt": "Continue with this",
  "transient_turn_context": "Fresh host facts for this turn"
}

{
  "session_id": "01936f8a-7b2c-7000-8000-000000000001",
  "prompt": "",
  "stream": false,
  "verbose": false,
  "tools": [],
  "tool_results": [
    {
      "tool_use_id": "tc_abc123",
      "content": "File contents here...",
      "is_error": false
    }
  ],
  "enable_builtins": false,
  "builtin_config": null,
  "keep_alive": null,
  "comms_name": null,
  "model": null,
  "max_tokens": null,
  "provider": null,
  "hooks_override": null
}

{
  "content": [{
    "type": "text",
    "text": "{\"content\":[{\"type\":\"text\",\"text\":\"Agent is waiting for tool results\"}],\"session_id\":\"01936f8a-7b2c-7000-8000-000000000001\",\"status\":\"pending_tool_call\",\"resumable\":true,\"pending_tool_calls\":[{\"tool_use_id\":\"tc_abc123\",\"tool_name\":\"read_file\",\"args\":{\"path\":\"/tmp/data.txt\"}}]}"
  }]
}

Decode the pending payload from content[0].text. It is a control result with status: "pending_tool_call", session_id, resumable: true, pending_tool_calls, and human-readable content, not a completed-run payload. A session_ref may be present when assigned by the surface; session_created: true, when present, says that the suspended request created the session (false is omitted). Do not infer successful-run counters from a pending result. Echo each provider-issued tool_use_id exactly in tool_results, as tc_abc123 is echoed above. Never correlate by tool name or array position, even when several pending calls invoke the same tool.

Parameter reference

string

required

Session ID to resume.

string

required

Follow-up prompt (can be empty when providing tool results).

bool

default:"false"

Stream agent events via notifications/message; see event streaming.

bool

default:"false"

Enable verbose event logging.

array

default:"[]"

Tool definitions (should match the original run).

array

default:"[]"

Tool results for pending tool calls.

string

required

Exact provider-issued tool_use_id from the matching pending call.

string

required

Result content (or error message).

bool

default:"false"

Whether this is an error result.

bool | null

default:"null"

Builtins override. Omit / null to inherit the persisted session value.

object | null

default:"null"

Builtin tool config.

bool | null

default:"null"

Shell-tools override. Omit / null to inherit the persisted session value.

bool | null

default:"null"

Keep-alive override for this resume. null = inherit persisted session intent, true = enable, false = disable.

meerkat_run and meerkat_resume follow the same commit/cancel rule as the other interactive surfaces: committed success is not rewritten to cancellation, and post-commit create failure returns session identity so the session can be resumed.

string | null

default:"from session"

Agent name for comms.

string | null

default:"from session"

Model override. On materialized sessions this hot-swaps the LLM client for the remainder of the session.

u32 | null

default:"from session"

Max tokens override.

string | null

default:"from session"

Provider override for mid-session switching with model: "anthropic", "openai", "gemini", or "other", as on meerkat_run. Omission/null permits normal model/binding resolution; "self_hosted" is not an accepted explicit token.

HookRunOverrides | null

default:"null"

Run-scoped hook overrides.

Response format

Both meerkat_run and meerkat_resume return MCP-standard tool results. Parse the JSON-encoded content[0].text payload. Completed runs contain the fields below; callback-pending control results use the distinct shape above.

array

MCP content blocks with the agent’s text.

string

Session ID (save for meerkat_resume).

u32

Number of LLM calls made.

u32

Number of tool calls executed.

JSON | null

Parsed structured output when extraction succeeds, or explicit null.

ExtractionError | null

Post-turn extraction failure details, or explicit null. The object has last_output (the committed main-turn assistant text extraction tried to transform), attempts (number of extraction attempts), and reason (human-readable failure description).

array | null

Schema compatibility warnings.

The main turn can successfully return committed text in content even if post-turn extraction fails. Inspect both structured_output and extraction_error; missing structured output does not prove extraction was never requested. Unlike REST/RPC WireRunResult, the MCP completed-run inner payload includes explicit null values for these absent optional fields; the outer MCP text wrapper remains unchanged.

meerkat_config

Get or update realm config for this MCP server instance.

{ "action": "get" }

{
  "action": "set",
  "config": { "agent": { "model": "gpt-5.5" } },
  "expected_generation": 3
}

{
  "action": "patch",
  "patch": { "agent": { "max_tokens_per_turn": 8192 } },
  "expected_generation": 4
}

string

required

One of "get", "set", "patch".

object | null

Full config to replace (for set action).

object | null

RFC 7396 merge-patch delta (for patch action).

u64 | null

Optional optimistic concurrency check for set and patch.

Response includes config envelope fields:

config
generation
realm_id
instance_id
backend
resolved_paths (only when the server runs with --expose-paths)

The MCP surface returns only the ConfigEnvelope shown above. It does not carry the live_propagation field: that is part of the richer JSON-RPC ConfigWriteResult contract, which reports the per-channel hot-swap / refresh / close outcome (swapped, skipped, swap_failed, refreshed, closed, refresh_failed, close_failed) when a set/patch write fans out to live channels. Use the JSON-RPC config/set / config/patch methods when you need the typed live-propagation report.

meerkat_capabilities

Returns the runtime capability set with status resolved against config.

{}

{
  "contract_version": {"major": 0, "minor": 8, "patch": 42},
  "capabilities": [
    {
      "id": "sessions",
      "description": "Session lifecycle management",
      "status": "Available"
    },
    {
      "id": "structured_output",
      "description": "Structured output extraction with JSON schema",
      "status": "Available"
    },
    {
      "id": "hooks",
      "description": "Lifecycle hooks for tool and turn events",
      "status": "Available"
    },
    {
      "id": "builtins",
      "description": "Built-in tools (task management)",
      "status": {"DisabledByPolicy": {"description": "Disabled by config"}}
    },
    {
      "id": "shell",
      "description": "Shell command execution",
      "status": {"DisabledByPolicy": {"description": "Disabled by config"}}
    },
    {
      "id": "comms",
      "description": "Inter-agent communication",
      "status": {"NotCompiled": {"feature": "comms"}}
    },
    {
      "id": "memory_store",
      "description": "Semantic memory indexing",
      "status": "Available"
    },
    {
      "id": "skills",
      "description": "Skill loading and injection",
      "status": "Available"
    }
  ]
}

Possible status values:

Status	Shape	Meaning
`Available`	`"Available"`	Compiled in, config-enabled
`DisabledByPolicy`	`{"DisabledByPolicy": {"description": "..."}}`	Compiled in but disabled
`NotCompiled`	`{"NotCompiled": {"feature": "..."}}`	Feature flag absent
`NotSupportedByProtocol`	`{"NotSupportedByProtocol": {"reason": "..."}}`	Protocol does not support it

meerkat_models_catalog

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

{}

{
  "contract_version": {"major": 0, "minor": 8, "patch": 42},
  "providers": [
    {
      "provider": "anthropic",
      "default_model_id": "claude-opus-5-5",
      "models": [
        {
          "id": "claude-opus-5",
          "display_name": "Claude Opus 5",
          "tier": "recommended",
          "context_window": 1000000,
          "max_output_tokens": 128000,
          "profile": {
            "model_family": "claude-opus-5",
            "supports_temperature": false,
            "supports_thinking": true,
            "supports_reasoning": false,
            "params_schema": {}
          }
        }
      ]
    }
  ]
}

No parameters required. The catalog is resolved from built-in model metadata plus config-backed provider/server entries.

meerkat_skills

List available skills with provenance information, or inspect one skill’s full body by typed SkillKey.

{ "action": "list" }

{
  "action": "inspect",
  "skill_key": {
    "source_uuid": "00000000-0000-4b11-8111-000000000001",
    "skill_name": "task-workflow"
  }
}

{
  "action": "inspect",
  "skill_key": {
    "source_uuid": "00000000-0000-4b11-8111-000000000001",
    "skill_name": "task-workflow"
  },
  "source": "00000000-0000-4b11-8111-000000000001"
}

{
  "skills": [
    {
      "key": {
        "source_uuid": "00000000-0000-4b11-8111-000000000001",
        "skill_name": "task-workflow"
      },
      "name": "Task Workflow",
      "description": "How to use task tools",
      "scope": "builtin",
      "source": {
        "source_uuid": "00000000-0000-4b11-8111-000000000001",
        "display_name": "embedded",
        "transport_kind": "embedded",
        "fingerprint": "embedded:inventory",
        "status": "active"
      },
      "is_active": true
    }
  ]
}

{
  "key": {
    "source_uuid": "00000000-0000-4b11-8111-000000000001",
    "skill_name": "task-workflow"
  },
  "name": "Task Workflow",
  "description": "How to use task tools",
  "scope": "builtin",
  "source": {
    "source_uuid": "00000000-0000-4b11-8111-000000000001",
    "display_name": "embedded",
    "transport_kind": "embedded",
    "fingerprint": "embedded:inventory",
    "status": "active"
  },
  "body": "# Task Workflow\n\n..."
}

string

required

"list" to list all skills, or "inspect" to load one skill’s full body.

object

Required for inspect. The typed skill identity with source_uuid and skill_name fields.

string

Optional source UUID selector for inspect; omit it to load the canonical source for skill_key.

The list response includes both active and shadowed skills. Shadowed skills have is_active: false and a shadowed_by field indicating which source has precedence. Inspect canonicalizes skill_key through the identity registry before loading the body.

​Getting started as a client

​Tool overview (server mode)

​Surface boundaries

​Use MCP servers as tools (client)

​CLI configuration (recommended)

​Config file format

​Meerkat as an MCP server

​Connecting other clients

​Hosting the MCP server

​Logging

​Request cancellation

​Event streaming

​Push notifications

​Pull streams: open, read, close

​Tool reference

​meerkat_run

​Parameter reference

​McpToolDef schema

​meerkat_resume

​Parameter reference

​Response format

​meerkat_config

​meerkat_capabilities

​meerkat_models_catalog

​meerkat_skills

Getting started as a client

Tool overview (server mode)

Surface boundaries

Use MCP servers as tools (client)

CLI configuration (recommended)

Config file format

Meerkat as an MCP server

Connecting other clients

Hosting the MCP server

Logging

Request cancellation

Event streaming

Push notifications

Pull streams: open, read, close

Tool reference

meerkat_run

Parameter reference

McpToolDef schema

meerkat_resume

Parameter reference

Response format

meerkat_config

meerkat_capabilities

meerkat_models_catalog

meerkat_skills