AgentToolDispatcher, and the engine handles dispatch, parallel execution, and result injection. MCP servers are first-class — register them and their tools appear alongside your custom tools with no code changes.
Mental model
At the concept level, tools answer one question: how does the agent act on the world? The important conceptual layers are:- custom tools you own
- built-in tools Meerkat can compose
- MCP-provided external tools
- runtime visibility/scoping rules
Custom tools
Implement theAgentToolDispatcher trait:
ToolCallView is a zero-allocation borrowed view ({ id: &str, name: &str, args: &RawValue }). When the model requests multiple tool calls, Meerkat dispatches them in parallel.
MCP servers
Register any MCP server and its tools automatically appear in the agent’s tool set:.rkat/mcp.toml (project) or ~/.rkat/mcp.toml (user). Supports stdio, streamable HTTP, and SSE transports. OAuth-protected HTTP servers discover auth at connect time; use rkat mcp login <name> or rkat run --mcp-auth interactive when browser login is needed. See the MCP reference for full details.
MCP Apps in UI hosts
A host with an isolated MCP Apps renderer can opt in withAgentFactory::mcp_apps(true). Its MCP connections advertise
io.modelcontextprotocol/ui and capture the original tool definition,
arguments, full CallToolResult and available UI resource before model
projection. Headless factories leave this capability disabled.
App authors use standard _meta.ui.resourceUri, ui:// resources and
text/html;profile=mcp-app. UI-only result _meta remains in native session
persistence, outside model requests and public transcript projection. Resource
reads do not require the resource to appear in resources/list.
ToolAudience separates model and app visibility while retaining normal tool
scope and policy checks. MCP tools default to both audiences; explicit
_meta.ui.visibility narrows them. An app-only tool is unavailable to model
selection and deferred catalog search/load. Visibility is not authorization:
every app action still enters the current member’s native tool policy.
UI hosts submit ToolApplicationControlRequest through SessionService with a
trusted, revalidatable ingress and an exact session/tool-call locator. Governed
hosts must implement fresh tool-application authorization through their native
work-policy owner. The prior agent run’s authorization is never reused. Resource
context providers implement prepare_resource separately from tool-call
credential preparation.
Native session-service App IO can run while the model turn continues. Each
request uses an executor minted by the original Agent with its current tool
scope and configured hooks and review. Results without session effects or hook
notices return without loading or saving the accumulated transcript. Actual
effects and notices wait for that exact actor to apply them; persistent services
commit them before response delivery. This decision uses the collected outcome,
not readOnlyHint; a post-hook error or a disconnected caller does not cancel
required settlement. Custom SessionAgent implementations that do not provide
this executor keep serialized execution.
The runtime binds live operations to the originating physical MCP connection.
Retained views can replay without re-executing the tool; retirement, replacement
or process restart refuses new IO against the old binding. App code cannot pick
another server by supplying a name. Developer panels belong to the embedding
product’s Console integration. An MCP App can use its own renderer for a
versioned generated UI document without another host authoring contract.
Built-in tools
Meerkat ships with tool categories resolved per agent. Factory category flags default off; product surfaces may apply their own explicit preset (for example, the CLI defaults to--tools safe).
Shell tools support allow/deny list security policies. Runtime tool visibility can also be shaped with mob overlays and turn-boundary tool-scope updates. See the built-in tools reference for parameter details.
Image generation and web search are independent category decisions. Enabling
either one does not implicitly expose general builtins. Conversely, disabling
general builtins does not prevent a runtime-backed build from explicitly
enabling one of those capabilities. Explicit enables fail closed when the
selected runtime cannot provision the requested capability.
The current direct
rkat run, REST, and JSON-RPC session builders leave image
generation at inherit. In a normal composite dispatcher, that can expose
generate_image when the session identity, image machine, executor, planner,
and blob store are wired and tool visibility policy permits it. The minimal
no-builtins/no-shell path instead needs an explicit image-generation Enable
to avoid the factory’s early return. These direct surfaces do not expose that
enable switch. --allow-tool generate_image only narrows an already composed
surface; it cannot provision missing dependencies or enable the category.
For nontrivial Meerkat-owned tool families, companion skills provide the agent
instruction manual. Tool descriptions stay short and schema-oriented; skills
such as workgraph-workflow, schedule-workflow, task-workflow, and
shell-patterns explain the operating posture for the tool family.
Execution contracts
Tool visibility and tool execution are separate decisions. A visible tool has an execution contract that declares the modes it supports:- fast execution for ordinary request/response calls
- streaming execution with progress and cancellation policy
- detached execution backed by a durable job record
non_resumable: its durable job
truth survives a host restart, but a lost subprocess becomes worker_lost and
is never silently replayed.
Tool definitions also carry source provenance, and dispatchers classify calls
as read-only, mutating, or unknown. Hooks and policy layers receive those typed
facts rather than inferring authority from a tool name.
Tool scoping
Tool visibility can change during a session without restarting the agent. Changes are staged then atomically applied at the turn boundary — the LLM never sees a tool list change mid-stream. External filters. Callers can stage an allow-list or deny-list filter programmatically throughToolScopeHandle. This is distinct from MCP server lifecycle management.
Per-turn overlays. Mob flow steps can restrict tools for a single turn via TurnToolOverlay (allow + deny). The overlay is ephemeral — it’s cleared after the turn completes.
Live MCP mutation. MCP servers can be added or removed from a running session. Additions connect the server and register its tools; removals drain in-flight calls before finalizing. Both are staged and applied at the next turn boundary.
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.
Live MCP controls
MCP servers can be added, removed, or reloaded on a running session via JSON-RPC, REST, MCP-server tools, or SDK helpers:
All mutations are staged and applied at the next turn boundary. Set
persisted: true to write the change to disk config so it survives restart. See the RPC reference for full parameter details.
Since 0.9.4 the tool_config_changed event that reports the outcome carries settled, which says whether the change is a settled lifecycle fact rather than a pending or draining step; it never said whether anything was written to config. Events and notices stored by 0.9.3 and earlier carry persisted in its place, so a reader should accept either key. The persisted field of mcp/add, mcp/remove and mcp/reload keeps its name and meaning.
Surface availability
See the built-in tools reference for the mechanical details of factory flags and per-build overrides.
Scoped tool grants
A build can mark built-in tool families, individual tool names and MCP servers grant-gated. A gated name is mounted, a gated family as if it were enabled, and every tool a gated MCP server provides is gated from the moment it appears, but each stays hidden from the model and is refused at dispatch until a live scoped tool grant that covers it is admitted. A grant never widens a session past its build: it opens only what the build gated, and the static tool policy, the application tool policy, governed authority, review and confinement all still apply to every call it opens.- Gating a build. In Rust, set
grant_gated_toolsonSessionBuildOptionsorAgentBuildConfig, for exampleGrantGatedTools::default().with_family("shell").with_tool("deploy"); over JSON-RPC, passgrant_gated_tools({"families": [...], "tools": [...]}) tosession/create. The session records its gate, and a resume that names none restores it. The factory refuses a gate that no grant could honour withBuildAgentError::GrantGate: an unknown family, a gated family the build disables, a gated family none of whose tools the build mounts (comms tools mount only with a comms runtime), a gated name the build does not mount (a name a still connecting MCP server may provide is gated from the moment it appears), a name the build’s tool policy refuses, and a build without the runtime’s grant service. A gate that coversweb_search, by name or through its family, disables the provider’s native tools for the session, including native search that the session’s or a turn’s provider params ask for, so the gated tool is the only search path. - Gating a mob member. A mob profile declares
tools.grant_gated(grant_gated = { families = ["shell"], tools = ["deploy"] }in TOML; onmob/create, a realm profile or amob/spawnprofile override). At every member build, resume included, the member’s gate is its own profile’s gate joined with its role’s current gate. A store-owned identity declared with its role’s named profile is built from the role’s definition, as a worker of the role is: its own gate is the role’s current gate, less the families its declaration switches off. One declared with an exact profile of its own (profile_override) joins the role’s gate as role entries, as a member spawned with its own profile does. A family of the member’s own gate is mounted, closed by the gate, whatever its switch: leave the switch off, so a binary that does not know the gate keeps the family off. A role entry never fails the member’s build: a role tool name is gated from the moment it appears, a role family is gated where the member mounts it, and a role family the member does not mount (its switch off, or a spawn disabled it) or a role name the build’s tool policy refuses is ignored. A live member keeps the gate its build installed until its next build. A member whose own gate or role gate names anything cannot be placed on another host. - Gating MCP servers. A gate’s
mcp_serversnames MCP servers (in Rust,GrantGatedTools::with_mcp_server;{"mcp_servers": [...]}over JSON-RPC and in a mob profile’sgrant_gated). A gated server need not be configured: it may be attached later, and its tools are gated by their provenance from the moment they appear; each model-request boundary also gates the names a gated server provides then, so a name such a server had stays gated for the rest of the build, whichever source provides it later.unconfigured_mcp_servers: true(with_unconfigured_mcp_servers) gates every MCP server the build does not configure itself, whatever path attaches it later (mcp/addincluded); the servers the build configures stay open. A host’s callback tools and tool bundles are never a server’s. A gated server the build configures starts no process until a live grant of that server covers it when a build reads the grants (a respawn or a resume): until then nothing of it is connected, and a call naming one of its tools finds no tool. The build decides this itself as it composes the session’s tools; MeerkatMachine’s gated stage (SurfaceStageGatedAdd,McpRouter::stage_add_gated) is the check of a grant-time live attach of a gated server, and its caller lands with the live attach. A tool name only a gated server provides is granted through its server, not by name. A role server, like a role tool name, is gated from the moment it appears and never fails the member’s build. - Granting.
MeerkatMachine::grant_toolissues a grant for a subject (a session, or a mob member identity in one mob incarnation,ToolGrantSubject::member), a target (one tool name, a built-in family with the names it provides, whichmeerkat::tool_family_namesanswers, or an MCP server, optionally narrowed to some of its tools) and a window of at most the host policy’s maximum lifetime, 24 hours by default. A grant can also be scoped to one run of its subject (ToolGrantRequest::run_scope; over JSON-RPC,scope: {"kind": "current_run"}takes the run the subject is running now, an identity’s being the run of the session its member holds, and is refused withrun_not_activewhen it runs none): it then admits uses of that run only, and ends with it; a member’s end of its run ends the run-scoped grants of its identity and of its session.revoke_tool_grant,list_tool_grantsandread_tool_grant_auditcomplete the Rust API;ToolGrantServiceoffers the same operations over anyRuntimeStore. Grant a mob member identity withMobHandle::grant_member_tool: the mob’s actor decides it against its live roster as it commits, in order with the retirements that end an identity’s grants, so a member retired before the commit is refused and a retirement after the commit ends the grant. The direct writers,MeerkatMachine::grant_toolandToolGrantService::grantwith a member subject, do not consult the roster: a grant they write for an identity that has retired is issued, and a name seated again in the same incarnation holds it. Over JSON-RPC,tool_grants/grant,tool_grants/revoke,tool_grants/listandtool_grants/auditserve them for sessions and mob member identities (see scoped tool grants over JSON-RPC), and the Python and TypeScript SDKs wrap them;tool_grants/grantcommits an identity grant through the mob’s actor. A member’s build reads its identity’s grants first, then its session’s, so an identity grant follows the member across respawns and restarts; its grants end when its identity ends, and a reset of its mob, which ends every identity the mob held, ends them too. - Requesting. A host can ask for a grant that a person approves instead
of issuing it:
MeerkatMachine::request_tool_grant, ortool_grants/requestover JSON-RPC (Pythonrequest_tool_grant, TypeScriptrequestToolGrant), holds a durable decision of kindtool_grant.issue(see durable decisions) and issues nothing. Every gated build also mounts the toolrequest_tool_grant, itself ungated, through which the agent asks for one of its gated names or families: it names the target,duration_msand areason, never the session or the approver, and the call returns at once with the pending request (a replayed call answers the request it held; a call for a target the session’s subject already has an open or approved window request for joins that request while it is open, and holds a new one after it ends; a joined request keeps its own duration, which can differ from the one asked, and the answer says the call joined and gives thatduration_ms). The session’s host holds it with what it takes requests with (MeerkatMachine::set_tool_grant_request_host: the decision owner, the approver policy and the requester its agents are named by;rkat-rpctakes them while it runs the executor), or the call answers that the host takes none. Once a person approved the decision, the executor of the kind (ToolGrantIssueExecutor, whichrkat-rpcruns) issues the grant under an id derived from the decision, with the decision as its issuer and its window starting then; a review stage’s allow never issues one. A list shows an open request asrequestedand, with ended grants, a recently rejected, expired, withdrawn or refused one asdeclined; the session receives an input when its request ends (a member identity’s request reaches the session its member holds then, through the mob’s member input). - Adjudication. Every model-request boundary first gates the names each
gated MCP server provides now, then opens the gated names a live grant
admits at that moment, in the boundary’s run (a server grant opens its
server’s gated names then), and every gated call is adjudicated again
immediately before it is handed to its tool, so a call at or after the
deadline is refused even when the boundary that showed the tool ran before
it. A run-scoped grant admits only the calls of its own run: a call outside
any run is refused and leaves the grant live for its run, and a call or
boundary of a later run ends it. A build belongs to no run, so a run-scoped
server grant starts no gated server the build configures; it opens the
names of a gated server that is attached during its run. The dispatch gate
authorizes a gated MCP call before the host prepares it
(
McpCallContextProvider::prepare), so a refused call never selects a credential. A refusal is an ordinarypolicy_deniedtool error with the codetool_grant_required,tool_grant_expired,tool_grant_revokedortool_grant_unavailable(a grant that ended with its run, or a run-scoped grant asked outside its run, opens nothing:tool_grant_required), which the model reads asTool call denied (<code>): <message>; a call of a closed gated tool behind the deferred catalog is refused the same way. When the grants cannot be read, or a boundary cannot gate a gated server’s names, the gate stays closed and the session records a warning notice. - Lifecycle. The canonical
ToolGrantLifecycleMachineowns each grant: issued, then expired at its fixed deadline, revoked before it, or, for a run-scoped grant, ended with its run before it. The run’s end ends the grant when the run completes, fails or is cancelled (a run a hard interrupt dropped included), when durable-tail recovery closes a run a stopped process left open, and otherwise at the first use of a later run of the session. Recovery ends the session’s run-scoped grants of the run it closes; a member identity’s run-scoped grants of a recovered member run end at the member’s next run’s first use, or at their deadline. Ended grants stay ended across restarts and host clock rollbacks. The runtime’s deadline timer expires a served session’s grants on time, and a list or audit read settles the due grants of any session without loading it; nothing about a grant wakes a dormant member. Grants live in the runtime store, on SQLite in theruntime-tool-grantsschema domain that the first write of a grant or audit row creates (a refused call’s audit row is one). With the in-memory store, Web/WASM included, they last only for the process. - Audit. Each subject’s grants append to one audit log:
granted(with the grant’s scope),expired(with the driver that observed the expiry),revoked,run_ended(with the run and the driver that ended it:runat the run’s end,recovery, or theboundaryordispatchof a later run) andrefusedrows. A lifecycle row commits with the grant’s change; a failed refusal row never admits the call. - Limits. The dispatch gate is the authority; what the model is shown
follows it at the next model-request boundary. A live session keeps the
tool surface its live bridge opened with, so a name a grant opened stays
visible there after the grant ends, and the dispatch gate refuses each call. A control-plane
tool, such as the deferred catalog’s search and load tools, is never hidden
by a gate; a gated one is refused at dispatch until a grant opens it. A
grant row this binary cannot read (written by a newer binary, or damaged)
opens nothing and blocks none of its subject’s other grants; a list reports
it, and an audit read reports an audit row it cannot read and serves the
rest of the page. A binary older than run scopes reads a run-scoped grant’s
row, and its
grantedandrun_endedaudit rows, so: it never takes a run-scoped grant for a window grant. A binary older than grant requests reads the grant an approved request issued as unreadable, so it opens nothing there. A binary older than scoped tool grants does not know a session’s gate: it resumes a gated session with its gated tools ungated, so upgrade every host that serves gated sessions before relying on a gate.
CompiledMemberToolGrant) decide which tools a member may use and with what
consequence. Both still apply to a call a scoped grant opened.
Asking a person (ask_user)
From 0.9.15. ask_user lets an agent put a set of multiple-choice questions to a person
and continue once they are answered. It is a stock tool that a host mounts:
meerkat-core defines the tool, its typed questions, answers and outcomes
and the seam a host implements (AskUserHost), and no build has the tool
until its host mounts it. A Rust host mounts it by putting an
AskUserDispatcher over its AskUserHost into the build’s host tools
(SessionBuildOptions::host_tools), which the agent factory composes beside
the build’s own tools and which leave the build’s tool catalog as it is.
Meerkat Meta mounts it for
mob members and answers it in its Console (see “Question sets” on that
page). No Core surface mounts it: not rkat, rkat-rpc, the REST server,
the MCP server or the Web SDK.
- Arguments.
questions(required), an optionaltitleand an optionaltimeout_seconds. Each question has anid, apromptandchoices(each anidand alabel), and may setallow_free_text(the person may write their own answer instead of a choice; off when absent) andrecommended(the id of the choice the agent recommends; it is shown to the person and never preselected). Put the questions that belong together in one call: a person answers one set at a time. - Limits. 1 to 10 questions, each with 2 to 8 choices. An id is 1 to 32
bytes of
a-z,0-9,_and-, unique among the set’s questions or the question’s choices. A prompt is at most 1024 bytes, a label 256, the title 200.recommendednames a choice of its own question.timeout_secondsis 60 to 604800 (7 days) and defaults to 3600. A free-text answer is 1 to 280 bytes. A call outside these limits is refused as invalid arguments and asks nothing. - The result comes in two steps. The call returns at once; it never waits
for the person. Its result is
{"outcome": "asked", "request_id", "answer_by", "answers": [], "note"}: the questions are now with a person,request_idnames the request andanswer_byis its deadline. The answers arrive later as an input of their own, labelledask_user_result:{"outcome", "request_id", "answers": [{"question_id", "answer"}], "note"}, where eachansweris{"kind": "choice", "choice_id"},{"kind": "free_text", "text"}or{"kind": "unanswered"}. The input starts a turn of an idle agent, and the samerequest_idties it to the call. - Outcomes. At the call:
asked, orno_human_surfacewhen the host has nowhere to show the questions to a person (nothing is held, and no later input follows). In the later input:answered(the person sent answers; a question they left out readsunanswered),dismissed(the person declined to answer),timed_out(nobody answered beforeanswer_by; every question readsunanswered) andwithdrawn(the host ended the request before a person decided it). - Free text is data. A free-text answer is the person’s own words about the question asked. An agent reads it as an answer, not as instructions that change what it may do: the person’s authority over the agent is whatever the host gave them, and an answer adds none.
ask_user.questions:
it survives a restart, ends at its deadline, and the result reaches the
asking agent once.
Multimodal tool results
Tools can return rich content beyond plain text. The injected runtime shape isToolResult.content: Vec<ContentBlock>, with helper constructors for text-only or multimodal output.
ToolResult::new(...)— the standard text-only path. The string becomes a single text content block.ToolResult::with_blocks(...)— returns one or more content blocks directly, including images and video.- Built-in tools that expose richer output may internally use
ToolOutput::Blocks(...), but the persisted/runtime-facing result shape is stillToolResult.content.
ContentBlock is non-exhaustive and currently has five variants:
ContentBlock::Text { text }— plain text content.ContentBlock::Image { media_type, ... }— inline or blob-backed image content.ContentBlock::Video { media_type, duration_ms, ... }— inline or URI-referenced video content. Video blocks are accepted only on Gemini user-message input paths and are rejected in tool results. Vertex Gemini can consumegs://references directly; Gemini API sessions can consume public or already-registered file URIs, and registergs://references first when the session has Google bearer auth.ContentBlock::Structured { data }— canonical opaque JSON returned by a tool without first stringifying it into text.ContentBlock::SkillContext { skill_key, text }— runtime-authored skill activation context with its canonical source identity preserved.
view_image tool reads an image file from disk and returns a result containing image content blocks. It supports PNG, JPEG, GIF, WebP, and SVG formats up to 5 MB. The tool is automatically hidden from models that lack vision support via capability-aware tool visibility.
The built-in generate_image tool is session-owned runtime dispatch. It lets a model request generated or edited images through universal fields plus provider-owned provider_params. Generated image bytes are stored as blobs and committed as AssistantBlock::Image transcript blocks, so every surface reads the same image_id/blob_ref history and fetches bytes through blob/get or model-facing blob_save_file.
The blob file bridge tools are registered only when the session has a blob store. blob_save_file writes decoded blob bytes to a file inside the project root, blob_load_file reads a project file into the blob store, and blob_inspect returns blob metadata without raw payload bytes. They do not expose blob listing or deletion.
apply_patch and blob_save_file run in the host process and never write the engine’s own directory (a .rkat directory at or below the project root) or a path the host declares as its own state or input; see paths the file tools never write.
Custom tools can return text, image, or structured content through
ToolResult::with_blocks(...). Video tool results are rejected, and
SkillContext is reserved for the runtime skill-injection path.
Image generation
generate_image is a session-owned tool for creating or editing assistant
images. It is registered when the runtime-backed surface supplies the
image-generation machine, provider executor, planner, and blob store. In the
normal composite dispatcher, Inherit is visible once that substrate is wired.
The category can also be enabled independently from general builtins through a
Mob profile or an in-process override_image_generation: Enable.
The tool accepts a typed request under request, routes it to OpenAI or Gemini image backends, stores generated image bytes in the realm blob store, and returns structured ImageGenerationToolResult JSON with durable images[].blob_ref values. A model can then call blob_save_file to materialize that blob as a project file, for example top-news-infographic.png.
For setup, provider parameters, result fields, and troubleshooting, see Image generation.
Composition
Tools from different sources (custom, MCP, built-in) are composed into a single dispatcher. The agent sees one flat tool list regardless of where each tool comes from. Hooks can observe tool calls before and after execution, and guardrails can deny unsafe calls before dispatch.Mob tools (meerkat-mob-mcp)
Mob tools (mob_*) are provided by the meerkat-mob-mcp dispatcher and composed
through the late-bound SessionBuildOptions.mob_tools factory slot.
- CLI
runcomposes this dispatcher when thefulltool preset is selected (--tools fullor--yolo). rkat mob ...remains the explicit direct lifecycle surface.- Other session-driven surfaces can grant the same agent-side
mob_*capability by installingAgentMobToolSurfaceFactoryinto their session build path. - Public host APIs should not re-export that raw dispatcher. They use typed
control planes instead:
mob/*on RPC/SDK surfaces andmeerkat_mob_*on public MCP surfaces.
