Tools & MCP

For concepts, see Tools.

If you are new to the tools system, start with Enable built-in tools, then Register MCP servers, then come back to Custom tools (Rust SDK) when you need to extend the runtime directly.

Start here

This page is structured from common product usage to advanced extension work:

enable built-in tools
register MCP servers
manage live MCP controls and tool scoping
implement custom Rust tools when you need to extend the runtime directly

Enable built-in tools

Built-in tool categories include general builtins, shell, semantic memory, schedule, WorkGraph, comms, mob orchestration, image generation, and web search. On the CLI, common groups are selected with tool presets. Other surfaces expose category booleans such as enable_builtins, enable_shell, enable_memory, enable_workgraph, enable_mob, and enable_web_search. Image generation and web search are independent from general builtins.

# Enable builtins + shell
rkat run --tools workspace "List files in /tmp"

# Short flag form
rkat run -t workspace "List files in /tmp"

# Enable mob orchestration too
rkat run --tools full "Coordinate the team"
rkat run --yolo "Coordinate the team"

{
  "jsonrpc": "2.0", "id": 1,
  "method": "session/create",
  "params": {
    "prompt": "List files in /tmp",
    "enable_builtins": true,
    "enable_shell": true,
    "enable_memory": true,
    "enable_mob": true
  }
}

curl -X POST http://localhost:8080/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "List files in /tmp",
    "enable_builtins": true,
    "enable_shell": true,
    "enable_memory": true,
    "enable_mob": true
  }'

{
  "prompt": "List files in /tmp",
  "enable_builtins": true,
  "builtin_config": {
    "enable_shell": true,
    "shell_timeout_secs": 30
  },
  "enable_memory": true,
  "enable_mob": true
}

Called via the meerkat_run tool.

session = await client.create_session(
    "List files in /tmp",
    enable_builtins=True,
    enable_shell=True,
    enable_memory=True,
    enable_mob=True,
)

const session = await client.createSession("List files in /tmp", {
  enableBuiltins: true,
  enableShell: true,
  enableMemory: true,
  enableMob: true,
});

let factory = AgentFactory::new(root)
    .builtins(true)
    .shell(true)
    .memory(true)
    .mob(true);

let service = build_ephemeral_service(factory, config, 64); // Queue-only embedded/testing substrate
let result = service.create_session(CreateSessionRequest {
    model: "gpt-5.6-sol".into(),
    prompt: "List files in /tmp".into(),
    system_prompt: SystemPromptOverride::Inherit,
    max_tokens: None,
    event_tx: None,
    initial_turn: InitialTurnPolicy::RunImmediately,
    deferred_prompt_policy: DeferredPromptPolicy::Discard,
    build: None,
    labels: None,
}).await?;

Run a durable background shell job

Ask the shell tool for background: true when you need Meerkat-owned job truth rather than shell syntax that happens to include &:

{
  "command": "./scripts/long-check.sh",
  "working_dir": ".",
  "timeout_secs": 900,
  "background": true
}

The submission returns before the process completes:

{
  "job_id": "job_019467d9-7e3a-7000-8000-000000000000",
  "status": "queued",
  "restart_class": "non_resumable",
  "awaitable": true,
  "message": "Durable shell job submitted with ID: job_019467d9-7e3a-7000-8000-000000000000"
}

Use shell_job_status, shell_jobs, and shell_job_cancel with that stable ID. The record survives restart, but the subprocess does not become resumable: a lost worker is terminally classified worker_lost and is not replayed. monitor_start is a separate high-trust, opt-in tool for scripts that emit framed notifications, checkpoints, progress, and completion. It is not enabled by the standard shell category alone.

Register MCP servers

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

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

# Add an OAuth-protected streamable HTTP server and log in
rkat mcp add --transport http knowledge https://mcp.example.com/v1
rkat mcp login knowledge

# List all registered servers
rkat mcp list
rkat mcp list --scope project --json

# Get details for a specific server
rkat mcp get filesystem

# Remove a server
rkat mcp remove filesystem

Config is stored in .rkat/mcp.toml (project) or ~/.rkat/mcp.toml (user). Project scope wins on name collisions. Each server supports an optional connect_timeout_secs field (default: 10 seconds) covering the entire connect + handshake + tool enumeration budget:

# .rkat/mcp.toml
[[servers]]
name = "slow-server"
command = "npx"
args = ["-y", "@my/slow-mcp-server"]
connect_timeout_secs = 30

Live MCP controls

Add, remove, or reload MCP servers on a running session without restarting the agent. Changes are staged and applied at the next turn boundary.

CLI rkat mcp add/remove/list/get manages server config (persisted to .rkat/mcp.toml or ~/.rkat/mcp.toml). The methods below manage servers on a running session — changes are staged and applied at the next turn boundary.

JSON-RPC
REST
MCP
Python
TypeScript

{
  "jsonrpc": "2.0", "id": 2,
  "method": "mcp/add",
  "params": {
    "session_id": "01936f8a-...",
    "server_config": {
      "name": "my-tools",
      "command": "npx",
      "args": ["-y", "@my/mcp-server"]
    },
    "persisted": false
  }
}

{
  "jsonrpc": "2.0", "id": 3,
  "method": "mcp/remove",
  "params": {
    "session_id": "01936f8a-...",
    "server_name": "my-tools",
    "persisted": false
  }
}

{
  "jsonrpc": "2.0", "id": 4,
  "method": "mcp/reload",
  "params": {
    "session_id": "01936f8a-...",
    "server_name": "my-tools"
  }
}

# Add
curl -X POST http://localhost:8080/sessions/01936f8a-.../mcp/add \
  -H "Content-Type: application/json" \
  -d '{
    "server_config": {"name": "my-tools", "command": "npx", "args": ["-y", "@my/mcp-server"]},
    "persisted": false
  }'

# Remove
curl -X POST http://localhost:8080/sessions/01936f8a-.../mcp/remove \
  -H "Content-Type: application/json" \
  -d '{"server_name": "my-tools", "persisted": false}'

# Reload
curl -X POST http://localhost:8080/sessions/01936f8a-.../mcp/reload \
  -H "Content-Type: application/json" \
  -d '{"server_name": "my-tools"}'

// Reload a specific server
{"name": "meerkat_mcp_reload", "arguments": {
  "session_id": "01936f8a-...",
  "server_name": "my-tools",
  "persisted": false
}}

// Reload all servers
{"name": "meerkat_mcp_reload", "arguments": {
  "session_id": "01936f8a-...",
  "persisted": false
}}

await client.mcp_add(
    session_id="01936f8a-...",
    server_config={"name": "my-tools", "command": "npx", "args": ["-y", "@my/mcp-server"]},
    persisted=False,
)

await client.mcp_remove(session_id="01936f8a-...", server_name="my-tools", persisted=False)
await client.mcp_reload(session_id="01936f8a-...", server_name="my-tools")

await client.mcpAdd({
  session_id: "01936f8a-...",
  server_config: { name: "my-tools", command: "npx", args: ["-y", "@my/mcp-server"] },
  persisted: false,
});

await client.mcpRemove({ session_id: "01936f8a-...", server_name: "my-tools", persisted: false });
await client.mcpReload({ session_id: "01936f8a-...", server_name: "my-tools" });

Set persisted: true to write the change to disk config so it survives restart.

Tool scoping

Tool visibility can change during a session. Changes are staged and atomically applied at the turn boundary — the LLM never sees a tool list change mid-stream. External filters. Allow-list or deny-list filters are persisted in session metadata and survive resume. Per-turn overlays. Mob flow steps can restrict tools for a single turn via TurnToolOverlay. The overlay is ephemeral and cleared after the turn completes.

# Allow-list specific tools for this turn
rkat run --resume 01936f8a-... \
  --allow-tool shell --allow-tool read_file \
  --block-tool task_create \
  "Execute the next step"

{
  "jsonrpc": "2.0", "id": 5,
  "method": "turn/start",
  "params": {
    "session_id": "01936f8a-...",
    "prompt": "Execute the next step",
    "turn_tool_overlay": {
      "allowed_tools": ["shell", "read_file"],
      "blocked_tools": ["task_create"]
    }
  }
}

curl -X POST http://localhost:8080/sessions/01936f8a-.../messages \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "01936f8a-...",
    "prompt": "Execute the next step",
    "turn_tool_overlay": {
      "allowed_tools": ["shell", "read_file"],
      "blocked_tools": ["task_create"]
    }
  }'

{"name": "meerkat_resume", "arguments": {
  "session_id": "01936f8a-...",
  "prompt": "Continue with restricted tools",
  "turn_tool_overlay": {
    "allowed_tools": ["shell", "task_create"],
    "blocked_tools": []
  }
}}

result = await session.turn(
    "Execute the next step",
    turn_tool_overlay={
        "allowed_tools": ["shell", "read_file"],
        "blocked_tools": ["task_create"],
    },
)

const result = await session.turn("Execute the next step", {
  turnToolOverlay: {
    allowedTools: ["shell", "read_file"],
    blockedTools: ["task_create"],
  },
});

Composition rule: most-restrictive wins. Multiple allow-lists intersect, multiple deny-lists union, and deny always beats allow. The conversation records a typed tool_config system notice when the tool set changes, and a tool_config_changed event is emitted to the event stream.

Advanced: Custom tools (Rust SDK)

Implement AgentToolDispatcher to define your own tools. The agent sees them alongside built-in and MCP tools.

struct MathTools;

#[async_trait]
impl AgentToolDispatcher for MathTools {
    fn tools(&self) -> Arc<[Arc<ToolDef>]> {
        vec![Arc::new(ToolDef {
            name: "add".to_string(),
            description: "Add two numbers".to_string(),
            input_schema: json!({
                "type": "object",
                "properties": {
                    "a": {"type": "number"},
                    "b": {"type": "number"}
                },
                "required": ["a", "b"]
            }),
            provenance: Some(ToolProvenance {
                kind: ToolSourceKind::RustBundle,
                source_id: "math-tools".into(),
            }),
        })].into()
    }

    fn tool_mutation_class(&self, tool_name: &str) -> ToolMutationClass {
        if tool_name == "add" {
            ToolMutationClass::ReadOnly
        } else {
            ToolMutationClass::Unknown
        }
    }

    async fn dispatch(&self, call: ToolCallView<'_>) -> Result<ToolDispatchOutcome, ToolError> {
        match call.name {
            "add" => {
                let args: AddArgs = call.parse_args()
                    .map_err(|e| ToolError::invalid_arguments("add", e.to_string()))?;
                Ok(ToolResult::new(call.id.to_string(), format!("{}", args.a + args.b), false).into())
            }
            _ => Err(ToolError::not_found(call.name)),
        }
    }
}

Getting started

Concepts

Guides: Models And Hosting

Guides: Runtime Behavior

Guides: Orchestration

Examples: Foundations

Examples: Capabilities

Examples: Orchestration And Deployment

Start here

Enable built-in tools

Run a durable background shell job

Register MCP servers

Live MCP controls

Tool scoping

Advanced: Custom tools (Rust SDK)

Next step

​Start here

​Enable built-in tools

​Run a durable background shell job

​Register MCP servers

​Live MCP controls

​Tool scoping

​Advanced: Custom tools (Rust SDK)

​Next step

Start here

Enable built-in tools

Run a durable background shell job

Register MCP servers

Live MCP controls

Tool scoping

Advanced: Custom tools (Rust SDK)

Next step