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 @anthropic/mcp-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_read`	Read a session’s state
`meerkat_history`	Read a session’s committed transcript history
`meerkat_sessions`	List sessions in the active realm
`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_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_prefabs`	List built-in mob prefab templates (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)

When the mob feature is enabled, meerkat-mob-mcp mob lifecycle tools (e.g. mob_create, mob_list, mob_lifecycle) are also exposed alongside the meerkat_* tools listed above. Additionally, mob capability within sessions is provided by composing MobMcpDispatcher into SessionBuildOptions.external_tools used by meerkat_run/meerkat_resume.

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 @anthropic/mcp-server-filesystem /tmp

# Add a streamable HTTP server
rkat mcp add api --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 standalone MCP server process, add a thin binary wrapper around its tools_list() and handle_tools_call* entrypoints, or embed it in an existing MCP host. 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.2").

max_tokens

u32 | null

default:"config default"

Max tokens per turn.

provider

string | null

default:"inferred"

Provider: "anthropic", "openai", "gemini", "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 compiled from meerkat-models at build time.

meerkat_skills

List or inspect available skills with provenance information.

{ "action": "list" }

action

string

required

"list" to list all skills, "inspect" to inspect a specific skill.

skill_id

string

Skill ID to inspect (required when action is "inspect").

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.

CLI

APIs

​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