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.

Tool	Description
`meerkat_run`	Start a new agent session
`meerkat_resume`	Continue a session or provide tool results
`meerkat_config`	Get or update server config
`meerkat_capabilities`	Query runtime capabilities

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": "meerkat-mcp-server",
      "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 -- meerkat-mcp-server

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.

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

default:"2"

Max retries for structured output validation.

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

default:"false"

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

builtin_config

object | null

default:"null"

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

builtin_config.enable_shell

bool

default:"false"

Enable shell tools.

builtin_config.shell_timeout_secs

u64 | null

default:"30"

Default shell command timeout.

host_mode

bool

default:"false"

Run in host mode for inter-agent comms (requires comms_name).

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 session or provide tool results for pending tool calls.

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

default:"false"

Enable built-in tools.

builtin_config

object | null

default:"null"

Builtin tool config.

host_mode

bool

default:"false"

Enable host mode.

comms_name

string | null

default:"from session"

Agent name for comms.

model

string | null

default:"from session"

Model override.

max_tokens

u32 | null

default:"from session"

Max tokens override.

provider

string | null

default:"from session"

Provider override.

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 Meerkat 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).

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

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

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