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.

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
`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_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`	Stage system context for 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_flow_run`	Start a mob flow run (mob feature)
`meerkat_mob_flow_status`	Get flow run status (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_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 tools. Mob tools appear when the mob feature is compiled in.

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.

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 --transport http --url https://mcp.example.com/api

# 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}" }

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

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"
}

Parameter reference

prompt

string

required

User prompt for the agent.

system_prompt

string | null

default:"null"

Override system prompt.

model

string | null

default:"config default"

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

max_tokens

u32 | null

default:"config default"

Max tokens per turn.

provider

string | null

default:"inferred"

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

output_schema

object | null

default:"null"

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

structured_output_retries

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.

stream

bool

default:"false"

Stream agent events via MCP notifications.

verbose

bool

default:"false"

Enable verbose event logging (server-side).

tools

array

default:"[]"

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

enable_builtins

bool | null

default:"null"

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

builtin_config

object | null

default:"null"

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

builtin_config.enable_shell

bool | null

default:"null"

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

builtin_config.shell_timeout_secs

u64 | null

default:"30"

Default shell command timeout.

keep_alive

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.

comms_name

string | null

default:"null"

Agent name for comms.

hooks_override

HookRunOverrides | null

default:"null"

Run-scoped hook overrides.

McpToolDef schema

name

string

required

Tool name.

description

string

required

Tool description.

input_schema

object

required

JSON Schema for tool input.

handler

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"
}

Parameter reference

session_id

string

required

Session ID to resume.

prompt

string

required

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

stream

bool

default:"false"

Stream agent events via MCP notifications.

verbose

bool

default:"false"

Enable verbose event logging.

tools

array

default:"[]"

Tool definitions (should match the original run).

tool_results

array

default:"[]"

Tool results for pending tool calls.

tool_results[].tool_use_id

string

required

ID of the tool call.

tool_results[].content

string

required

Result content (or error message).

tool_results[].is_error

bool

default:"false"

Whether this is an error result.

enable_builtins

bool | null

default:"null"

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

builtin_config

object | null

default:"null"

Builtin tool config.

builtin_config.enable_shell

bool | null

default:"null"

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

keep_alive

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.

comms_name

string | null

default:"from session"

Agent name for comms.

model

string | null

default:"from session"

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

max_tokens

u32 | null

default:"from session"

Max tokens override.

provider

string | null

default:"from session"

Provider override. Typically inferred from model. Used with model for mid-session provider switching.

hooks_override

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:

content

array

MCP content blocks with the agent’s text.

session_id

string

Session ID (save for meerkat_resume).

turns

u32

Number of LLM calls made.

tool_calls

u32

Number of tool calls executed.

structured_output

object | null

Parsed structured output.

schema_warnings

array | null

Schema compatibility warnings.

meerkat_config

Get or update realm config for this MCP server instance.

{ "action": "get" }

action

string

required

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

config

object | null

Full config to replace (for set action).

patch

object | null

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

expected_generation

u64 | null

Optional optimistic concurrency check for set and patch.

Response includes config envelope fields:

config
generation
realm_id
instance_id
backend
resolved_paths

meerkat_capabilities

Returns the runtime capability set with status resolved against config.

{}

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.

{}

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

string

required

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

skill_key

object

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

source

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.

CLI

APIs

Documentation Index

​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