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 (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.

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 glean https://king-be.glean.com/mcp/default

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

# 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 = "glean"
url = "https://king-be.glean.com/mcp/default"

# 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. If you need a full public MCP host, embed its tools_list() and handle_tools_call* entrypoints or run the bundled rkat-mcp binary. If you need 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 realm scope flags:

rkat-mcp --realm team-alpha --instance worker-1 --realm-backend sqlite

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.

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-...\",\"turns\":1,\"tool_calls\":0,\"structured_output\":null,\"schema_warnings\":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"

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

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 MCP notifications.

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-...\",\"status\":\"pending_tool_call\",\"pending_tool_calls\":[{\"tool_name\":\"read_file\",\"args\":{\"path\":\"/tmp/data.txt\"}}]}"
  }]
}

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 MCP notifications.

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

ID of the tool 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. Typically inferred from model. Used with model for mid-session provider switching.

HookRunOverrides | null

default:"null"

Run-scoped hook overrides.

Response format

Both meerkat_run and meerkat_resume return MCP-standard tool results. The inner text field is a JSON-encoded payload containing:

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.

object | null

Parsed structured output.

array | null

Schema compatibility warnings.

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": 22},
  "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": "0.8.22",
  "providers": [
    {
      "provider": "anthropic",
      "default_model_id": "claude-opus-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)

​Use MCP servers as tools (client)

​CLI configuration (recommended)

​Config file format

​Meerkat as an MCP server

​Connecting other clients

​Hosting the MCP server

​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)

Use MCP servers as tools (client)

CLI configuration (recommended)

Config file format

Meerkat as an MCP server

Connecting other clients

Hosting the MCP server

Tool reference

meerkat_run

Parameter reference

McpToolDef schema

meerkat_resume

Parameter reference

Response format

meerkat_config

meerkat_capabilities

meerkat_models_catalog

meerkat_skills