Skip to main content
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

1

Add an MCP server

2

Verify it's registered

3

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. The base MCP tool surface below is declared and dispatched in the meerkat-mcp-server crate (crates/meerkat-mcp-server/src/lib.rs), which is the source of truth for tool names and availability.
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 and WorkGraph tools. Mob tools appear when the mob feature is compiled in. The WorkGraph Flow tools are advertised only by hosts that also configure a WorkGraph service. Their shared Mob runtime bridge owns reconciliation; MCP is only the transport adapter. Flow status carries a redacted reverse execution-binding reference when the run was launched by the bridge. Public binding views omit activation parameters, idempotency and correlation values, and execution principals.
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.
The multi-host console family adds the three observation tools only. Existing meerkat_mob_spawn and meerkat_mob_spawn_many mutations may carry placement for an already-bound host. Host admin (bind_host/revoke_host), grant admin (grant_scopes/revoke_scopes/grants), hard cancel, and member live-channel verbs remain deliberately absent — MCP servers are routinely wired into agent tool contexts, and an LLM-reachable admin mutation would be a privilege-escalation vector. Host/grant/live admin lives on JSON-RPC/SDK plus CLI; hard cancel is JSON-RPC/SDK-only. Unknown tool names fail closed.
resume_from_role is not accepted by meerkat_mob_spawn, spawn-many, helper, or profile tools. Durable member role migration is a one-request trusted-host operation available only to in-process SpawnMemberSpec and the private member-host materialization protocol. It is not an MCP permission or a standing profile setting.

Surface boundaries

The MCP server deliberately does not mirror every operator API: Session event streams are bounded live subscriptions. If a consumer falls behind, the stream yields the typed stream_truncated event with a StreamLagged dropped count and then continues with retained events. That is a live-delivery gap, not an EventStore projection result. Built-in realm-backed persistent sessions can feed a separate durable audit projector whose unbounded queue is independent of the UI ring. That projection is asynchronous derived state, so reconcile available replay/snapshot evidence with current session state when completeness matters.

Use MCP servers as tools (client)

Use the rkat mcp commands to manage MCP servers:

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.
Supported transports: stdio, streamable HTTP (default for URLs), and SSE. Environment variables in config use ${VAR_NAME} syntax.
cwd sets the working directory a stdio server is launched in; without it the server starts where it did before. The value is an absolute path used exactly as written: it is never expanded (no ${VAR_NAME}, no ~) or resolved. A relative, empty or NUL-containing cwd refuses the configuration when it is loaded, persisted, staged or connected. A cwd that is missing or not a directory when the server is launched refuses the launch before anything runs; there is no fallback to another directory. With cwd set, command must be an absolute path or a bare program name (checked after ${VAR_NAME} expansion), because a relative program path would resolve differently by platform. Under the host’s OS process confinement, cwd never widens what the server can reach: on Linux a directory outside the confinement’s mounts refuses the launch. A changed cwd is a changed server definition: it is launched anew, a resumed session’s recorded attachment to the old definition is refused as rebound, and realm service secrets (secret_env) stored for the old definition must be stored again. Mob portable profiles cannot carry cwd.
A streamable HTTP request is never re-sent after the server drops its session (404). A tool call whose own request is answered 404 for its session fails with the typed outcome_uncertain tool error (it may have taken effect). So does a call that fails after a redirect shown by its own returned response (a changed final URL, or a 3xx the policy did not follow). A transport failure with no response after a followed redirect cannot show that redirect and remains an ordinary failure; that neither proves the call had no effect nor makes a retry safe. Once the session is known expired, later calls on that connection are refused unsent until the host reconnects the server. A 404 on the session’s background SSE GET also marks the session expired; it does not change the outcome of a call already in flight, which can still succeed. A server that answers an unsupported GET with 404 instead of the specified 405 will see its sessions treated as expired and must be fixed to answer 405.
For OAuth-protected streamable HTTP servers, keep config simple. Add the URL with rkat mcp add and an account selection: --oauth-account <SUBJECT_ID> (the account the login must prove), --oauth-account-selection discover (bind the account the provider verifies at the first login) or --oauth-account-selection unverified (resource-bound access with no account evidence). Then run rkat mcp login <name> for an explicit browser login, or rkat run "..." --mcp-auth interactive to allow first-use browser auth during an interactive TTY run. Normal runs default to --mcp-auth stored. A server added without a selection is refused by rkat mcp login before any network request, with the commands for each choice.

The account an operation acts with

A reviewed operation (R2 or R3 under a realm’s governance settings) shows the reviewer and the consenting human the account it acts with, as the server’s owners state it for the exact connection the call runs on:
  • a connector binding (connector) states its issuer-verified account;
  • oauth_account = "<subject>" states that subject at the server’s origin; every credential the connection uses must prove it;
  • account = "none" is the host’s declaration that the server’s operations act with no selected account.
Anything else states nothing, and the operation’s review material is unavailable: its R2 or R3 review is refused locally, never run at R1. That includes a stdio server’s environment, a static Authorization header, an oauth_account_selection (a discovered subject lives only in the stored credential, and an unverified one carries no account) and a server without a connector binding. The account is fixed for the connection; a changed binding is a new connection, and a plan resolved on the old one is not dispatched. account = "none" conflicts with connector, oauth_account and oauth_account_selection. Only host configuration sets it: meerkat_mcp_add refuses it, and mob portable profiles cannot carry it.

Host-driven OAuth

MCP OAuth is a host ceremony. Agents never open a browser or see any of its data: when a server has no usable credential, its connection fails with the typed AuthorizationRequired status (McpError::AuthorizationRequired, McpRouter::servers_awaiting_authorization), and the host decides when to ask its user.
  • Account selection. Interactive login requires an account selection on the server entry, set only in host configuration:
    • oauth_account = "<subject>": the login must prove that account.
    • oauth_account_selection = "discover": the first login binds the account the strategy verifies, and publishes only into an empty credential slot. A later login reconnects only that same account with the same issuer, client, resource and strategy; anything else needs auth/logout first.
    • oauth_account_selection = "unverified": an explicit opt-in for servers that cannot prove an account. The credential is bound to the resource, issuer and client, but no account is verified or reported: account_id is always absent and status reports account_verification: "unverified" (host UI should say “account not verified”). No account strategy runs, and a re-login over an existing credential needs auth/logout first.
    Whoever administers the host’s configuration sets these keys: the project or user mcp.toml (rkat mcp add --oauth-account or --oauth-account-selection), or the host’s RPC and REST mcp/add. The meerkat_mcp_add management tool refuses both keys, because a host may expose that tool to an agent. The two keys conflict. Each selection has its own credential slot: changing it never reuses or migrates another selection’s credential, and a failed verification never falls back to unverified or to an unselected credential. A selected server must use streamable HTTP without a static Authorization header and a host OAuth resolver. Mob portable profiles cannot carry oauth_account_selection and refuse it. Credentials live in the host’s token store, one per installation (for rkat, files under the user’s config directory), with a credential slot per realm: the slot key includes the realm the host serves (HostAuthService::with_mcp_realm, which rkat and the RPC and REST servers set), so each realm logs in, refreshes and logs out on its own and never reads another realm’s credential. A credential stored before realms scoped these slots (0.9) is left unused. A new login over a Known credential stored before account bindings were recorded needs a disconnect first (using it does not). The default account strategy is OpenID Connect UserInfo: it requests openid, calls the issuer’s userinfo_endpoint with the new access token and reports sub, which must equal oauth_account when one is named. A refresh of a verified credential observes the subject again and refuses a different one; if the subject cannot be observed (for example no account strategy is installed) the refresh fails transiently and nothing is published. Hosts whose servers prove the account another way supply their own McpOAuthAccountStrategy. Start checks first that the account can be proven: for the default strategy, the issuer’s OpenID Connect discovery must name the exact issuer and an https (or loopback) userinfo_endpoint. An issuer that cannot is refused before client registration and before any browser opens. Hosts see these refusals as the typed auth reasons account_selection_required (no selection) and verification_unavailable (no account evidence); neither ever switches the server to unverified, so a host offers that mode only as the operator’s explicit choice. rkat mcp login prints the exact rkat mcp remove and rkat mcp add commands for each.
  • Discovery, registration and scopes. The authorization server’s metadata is read from RFC 8414 discovery, falling back to OpenID Connect discovery. Dynamic client registration declares application_type: "native". The attempt requires the scopes the server’s 401 challenge names (its scope), or else the resource metadata’s scopes_supported, in addition to the account strategy’s own; the completion is refused unless all of them are granted. offline_access is requested, never required, when the authorization server advertises it.
  • Credentials per request. An established connection reads its bearer from the credential owner on every request, so a refreshed credential is used without reconnecting. A request without a usable credential is refused before it is sent, and a request the server refuses with 401 fails with the typed AuthorizationRequired status. Neither is replayed. A custom McpAuthResolver must commit the credential its interactive_login returns, so that stored_bearer_token returns it from then on.
  • Embedding hosts use HostAuthService::mcp_login_start and mcp_login_complete (and mcp_login_cancel on timeout). Start admits the attempt through the runtime OAuth flow owner (PKCE and one-time state) and returns the authorize URL; complete takes the loopback callback, verifies it against the admitted attempt, exchanges the code and persists the credential. mcp_status reports the attempt pending for a server by a non-secret reference, which mcp_login_cancel_by_attempt_ref cancels, and mcp_logout retires any pending attempt and removes the server’s stored credential, so a callback admitted before the logout cannot store one. AgentFactory::mcp_auth_resolver (or AgentBuildConfig::mcp_auth_resolver) connects agents to those credentials. Runtime-backed RPC, REST and MCP-server hosts install this resolver by default, including for live mcp/add servers.
  • One attempt per server. A start while an attempt is pending for the same server returns that attempt (disposition: joined) instead of a second one. HostAuthService::mcp_begin_loopback_login binds the loopback callback for you; its pending login has a typed cancel that retires the callback binding and the attempt. Opening the browser is advisory: a failed launch never retries or cancels the attempt, which ends only by completion, cancel or expiry.
  • RPC and REST hosts use auth/login/start, auth/login/complete, auth/login/cancel and (RPC) auth/status/get with an MCP target instead of a provider binding:
    redirect_uri must be an http loopback URL, or the host’s registered https callback (next item). Completion sends only the callback’s code and state (and the same redirect_uri): issuer, client and resource come from the admitted attempt, and nothing network-facing happens until state is proven. Cancel takes {mcp, state}. A joined start returns the pending attempt’s URL and state, because wire callers are host-privileged by contract. A join reuses the pending attempt only if this host process admitted it after its account check; otherwise the attempt is retired and a fresh one started. While an attempt is pending, auth/status/get reports it as attempt: {ref, phase: "pending", expires_at}. The ref is not secret and grants nothing: a host that no longer holds the state (for example after its own restart) cancels with {mcp, attempt_ref}. RPC auth/logout with {mcp} retires any pending attempt and removes the server’s stored credential (nothing is revoked at the provider). Status and completion report account_verification (verified, unverified or legacy). The server must be configured (project or user mcp.toml of the host): server_url must equal its configured URL, and oauth_account or oauth_account_selection, if given, the configured value; they never select or change the mode. Anything else is refused before any network request.
  • Hosted callback (registered https redirect). A host whose users’ browsers cannot reach its loopback address (a server-hosted app) serves its own https callback endpoint and configures its base as host configuration: rkat-rpc --mcp-oauth-redirect-base https://host.example/mcp/oauth/callback, or HostAuthService::with_mcp_registered_redirect_base in an embedding host. Agents, MCP server definitions and mob profiles cannot set it. Each server’s exact redirect is the base followed by one path segment, its credential binding, so every server, realm and account selection has its own redirect (a slot whose pre-registered client names the base itself uses the base: see the central callback below). auth/login/start with redirect_uri set to the base (or to that server’s derived redirect) starts on it and adds two fields:
    host_attempt_handle is a secret: the host keeps it server-side with the ceremony it started, keyed by state, and never puts it in the browser, a URL, a model, a transcript or a log. attempt_ref is the public reference auth/status/get reports; it authorizes nothing. Dynamic registration registers a public PKCE web client for exactly the derived redirect; a server that answers with a confidential client is refused with its remedy before any attempt exists. The host routes the derived redirect to its callback endpoint, which must authenticate the user’s own session and match it to the session and realm that started the attempt, then call auth/login/complete once:
    redirect_uri must equal the admitted redirect byte for byte. iss (RFC 9207) must equal the attempt’s issuer byte for byte, and is required when the authorization server advertises authorization_response_iss_parameter_supported. A completion without the handle, with another one, or through a loopback-only path is refused (error.data.reason invalid_target, error.data.detail remote_custody_required) and leaves the attempt pending, so a forged callback cannot cancel it. The handle’s key lives in the runtime process: after a runtime restart, cancel the attempt with {mcp, attempt_ref} and start again. A joined start (an attempt already pending on the same redirect) carries no handle; an attempt pending on another redirect is refused (attempt_mismatch) until it is cancelled, and so is a loopback start while a registered attempt is pending. The credential lands in the same slot as a loopback login’s, with the same refresh, status, cancel and logout; a credential whose client was registered for the other redirect kind needs a logout first. The window is the same 300 s. REST and rkat mcp login serve loopback logins only.
  • Pre-registered clients (no dynamic registration). An authorization server that offers no dynamic client registration signs in only clients registered with it ahead of time. A native host installs such a client for one configured server with HostAuthService::mcp_install_client_profile (mcp_replace_client_profile, mcp_remove_client_profile, and their _entered forms; mcp_client_profile reads it back without the secret). An McpOAuthClientProfile names the authorization server’s issuer, the client id, the client’s exact registered redirect and its token endpoint authentication, client_secret_basic or client_secret_post, with the client secret. The redirect is the host’s registered base itself (the central callback, below), the server’s own registered https callback (the base followed by the slot’s binding segment), or an http loopback redirect on 127.0.0.1 or localhost with an explicit port. A registered https redirect that is neither this host’s base nor the slot’s own derived redirect, byte for byte, is refused at install and replace (configuration_invalid). HostAuthService::mcp_registered_redirect_uri answers the exact URI a slot logs in on (its profile’s, or its derived redirect without a profile): register that URI with the authorization server. Two optional fields cover servers whose metadata does not fit the defaults: with_scopes requests (and requires) the scopes the client is registered for in place of the ones the server names (offline_access is never required), and with_resource accepts the resource identifier the server’s protected resource metadata names when it is not the configured URL (only its origin or a path above it). Central callback: a host that serves many slots of one pre-registered client (several users, realms or account selections) registers one callback URI for all of them. Each slot’s profile names the host’s registered base itself, and every login of those slots is admitted on exactly that URI, byte for byte: a base such as https://host.example/services/mcp/callback stays exactly that, with no slash added or removed. The slots’ attempts are told apart only by their state and host_attempt_handle, so the host must route each callback by its state to the ceremony it retained when it started the login (the target and its host_attempt_handle) and complete it for exactly that target; it never takes the realm or account from the callback, the browser or a model. A callback presented for another slot is refused without consuming or retiring any attempt: a state that is not an attempt of that slot (attempt_missing) and a handle that is not that attempt’s custody (invalid_target, detail remote_custody_required) alike, so a misrouted or injected callback cannot cancel a user’s login. Only a callback that passes both checks and then fails (its redirect, issuer or code exchange) retires its attempt. A slot without a profile keeps its derived redirect. The profile belongs to one credential slot: the server as configured (name and URL), the realm the host serves and the account selection. It is never used for another server, realm or selection, and a profile stored for another slot is refused (configuration_invalid), never ignored. With a profile installed, a login of that server registers nothing and needs no registration endpoint. The server’s protected resource metadata must name the profile’s issuer (and its resource), or the start is refused (configuration_invalid) before any attempt exists. Under an https issuer, the token endpoint its metadata names, where the secret is sent, must use https as well, loopback included, or discovery refuses it (upstream_failure) and nothing is sent there; only an http loopback issuer, a local authorization server, keeps loopback endpoints. A refresh checks its stored token endpoint the same way and never sends the secret to one that does not fit: the credential is closed for a new login (reauth_required). The authorization request carries the profile’s client id and redirect, with PKCE S256. A start on any other redirect is refused (invalid_target); a loopback login through mcp_begin_loopback_login binds exactly the profile’s port and path. The code exchange and every refresh authenticate the client by the profile’s method, and a refresh token the server rotates is stored and presented by the next refresh. Without a profile nothing changes: dynamic registration as before. The attempt and the credential are bound to the profile’s facts, not to its secret. Replacing the profile with the same facts and a new secret keeps existing credentials refreshing with the new secret (and the next code exchange uses it); a secret the server rejects ends the credential. Removing the profile or replacing it with other facts ends what was bound to it: a pending attempt’s completion is refused (attempt_mismatch) and the attempt retired, and a credential’s next refresh is refused as reauth_required and the credential removed, so the user logs in again. Removal is not a revocation: the current access token stays usable until it expires, and mcp_status reports the credential Authorized until the refresh that ends it. To stop its use at once, call HostAuthService::mcp_logout, which removes the credential from the host (it revokes nothing at the authorization server). Ending the credential on a refresh the server rejects holds for standard OAuth error responses (for example invalid_client for a secret the server no longer accepts): a server that reports errors with HTTP 200 keeps the credential, every use retries the refresh and fails with a typed error, and mcp_status can keep reporting Authorized, as with Core’s other OAuth refreshes. Nothing is ever refreshed as a public client or through dynamic registration instead. A credential minted before the profile was installed keeps refreshing as the client it was registered as; a new login over it needs a logout first. Host obligations: install a profile only from the host’s own administration, never from agent input, a tool, an MCP server definition or a mob profile, and use the _entered forms so the host re-checks its authenticated administrator at the update’s entry. The secret lives only in the host’s credential store, beside the server’s credentials; it is never written to configuration and never appears in errors, events, logs or Debug output. Keep the profile in step with the client’s registration at the authorization server: its exact redirect, its authentication method and its secret. Profiles are a Rust host API: no RPC, REST or SDK method installs one. Attribution: an entry can state the administrator it admitted on its admission (EnteredAdministration::administered_by, with an AdministeringPrincipal, a qualified principal and optionally the digest of their login, and the host’s AdministrationRecorder). When the update settles, its owner hands the recorder one AdministrationRecord: the administrator, the login digest, the slot’s install, replacement or removal, whether it committed or its outcome is unknown, and when, also after the caller stopped waiting. The record names the slot by the server name, the realm and the credential binding, never by the server URL, which can carry credentials in its userinfo or its query. The _entered forms of the realm’s MCP service secrets (set_mcp_service_secret_entered, remove_mcp_service_secret_entered) and of realm configuration writes (ConfigRuntime::patch_entered, McpRealmPersistTarget::add_entered) record the same way. No record carries a value or secret, and Core keeps no copy: the host keeps the record in its own audit.
  • Bounded network stages. No stalled authorization server holds a login, its host or the credential. Each network stage of a login or refresh (protected resource metadata, authorization-server metadata, account preflight, client registration, the code exchange, account evidence, and a refresh’s token request and subject check) gets 20 s for all of its requests; a start’s stages get 60 s together, and a completion’s get 60 s together, never past the attempt’s 300 s window. Every credential request Core sends is also bounded at 30 s (10 s to connect). A stage that runs out of time ends the call with error.data.reason upstream_failure and error.data.detail upstream_timeout (the authorization code had not been sent) or upstream_timeout_after_code (it had, and may be spent at the provider; any tokens it issued are never stored). Nothing is published: a start admits no attempt and a completion’s attempt is retired, so start a new login. A refresh that runs out of time fails transiently and keeps the credential. Cancelling an attempt (auth/login/cancel by state or attempt_ref, or a logout) while its auth/login/complete is in flight ends that call at once with attempt_missing, and cancelled: true means nothing from that attempt is ever published. A cancel answered attempt_missing while a completion of the attempt is still in flight means the attempt is already gone: the credential commit consumed it, it expired, or an earlier cancel retired it. The completion answers its true end, or, when the commit has not reported within 60 s, error.data.reason commit_unsettled. Whether that credential landed is unknown until the commit settles; read auth/status/get later. It is neither a success nor a failure. A commit that fails after it consumed the attempt and cannot restore the previous credential also answers commit_unsettled; if a call to that server is then refused for authorization, log in again. A completion answered credential_access_pending was not admitted to its credential commit within 60 s: its attempt was retired and nothing from it is published, so start a new login. An embedding host that must know the outcome calls meerkat::settle_in_flight_credential_mutations and, once it answers Settled, reads HostAuthService::mcp_status, which reports what a use of the stored credential would do. An embedding host sets the bounds with HostAuthService::with_mcp_network_bounds.
  • Bounded discovery documents. A login reads at most 1 MiB of each document the servers it discovers answer with: the protected resource metadata, the authorization-server metadata (RFC 8414 or OpenID Connect discovery), the OpenID Connect configuration the account preflight reads, and the client registration response. The bytes are counted as they arrive, so a larger document is refused once 1 MiB has arrived and the rest is never read. Discovery and registration then end the call with error.data.reason upstream_failure, the account preflight with verification_unavailable, and the error names none of the document’s content. Nothing is published.
The authorize URL and state, and the callback’s code and state, let whoever holds them complete the attempt. A host must bind the loopback callback itself and never put these values in a tool result, transcript, agent event, elicitation result or log. It opens the URL in the user’s own browser: an ordinary host is supported, and no agent-unreachable host is required. A host whose agents have a browser or computer-use tool should not open the URL in a browser such a tool drives.

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 reads MCP servers from a .mcp.json file in your project root. Example stdio config:

Hosting the MCP server

meerkat-mcp-server is a library crate that provides tool schemas and handlers. For a full public MCP host, serve MeerkatMcpState::advertised_tools_list() from the same state used by the handle_tools_call* entrypoints, or run the bundled rkat-mcp binary. This instance-filtered catalog omits unavailable runtime tools, such as skills when no skill runtime is installed. meerkat_mcp_server::tools_list() is the static composable definition catalog, not the ready-to-serve instance catalog. For 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 the complete runtime scope flags:
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. OS process confinement flags (see OS process confinement):
They replace the realm’s composed [confinement] for every launch kind of this process. The workspace preset confines each launch to --context-root; without --context-root the server refuses to start with it. A start in which a confined process could change the server’s realm state or user config document is refused (see the host’s own inputs). At startup the server logs each launch kind’s requested and effective confinement and warns for each required kind its platform cannot confine. The bundled binary is stdio-only. If an embedding host publishes these tools over HTTP, that host owns transport authentication, authorization, and encryption; provider auth bindings configure outbound model credentials and do not authenticate inbound MCP callers.

Logging

rkat-mcp writes trace events to stderr only; stdout carries nothing but the MCP JSON channel. The default filter is info, which is what makes the verbose parameter of meerkat_run and meerkat_resume produce output. RUST_LOG replaces the default (RUST_LOG=warn keeps only warnings and errors; a blank value is treated as unset), and a value that does not parse is reported on stderr before the default applies, so an operator’s typo is never swallowed. Clients that capture stderr see these lines; nothing changes on stdout.

Request cancellation

The bundled server accepts MCP’s notifications/cancelled notification. While a tools/call request with JSON-RPC ID 2 is in flight, send:
Client -> server notification
requestId must be the original request’s exact ID, preserving its number/string type, not a session ID. This notification has no id and receives no response. It can cancel an uncommitted meerkat_run request before creation has returned a session identity. For example, cancellation before response publication can resolve that original request as:
Server -> client response to the original request
Cancellation does not roll back committed work: committed success is not rewritten to cancellation. This request lifecycle operation is distinct from meerkat_interrupt, which targets an existing session’s turn. Raw Meerkat JSON-RPC instead uses cancel with request_id; do not interchange those transport spellings.

Event streaming

Push notifications

Set stream: true on meerkat_run or meerkat_resume:
tools/call request
The bundled server emits MCP notifications/message messages while the request runs:
Push notification
The agent event is a full EventEnvelope<AgentEvent>; inspect params.data.event.payload, not params.data.event.type. Notifications have no request ID and do not replace the final tools/call response. A failure to serialize an event instead emits level: "error" with data.error: "event_serialization_failed" and data.message.

Pull streams: open, read, close

Pull streams are independent tool handles, not push notifications. Invoke these names via tools/call: The three mob tools require the mob feature. Each pull-tool result wraps its payload as JSON text in result.content[0].text; parse that string once. For example:
Read with flat timeout fields (there is no nested timeout object):
Read session stream
timeout_ms is an optional non-negative millisecond count. Omission/null uses the production default of 5000 ms; no_timeout defaults to false. no_timeout: true waits indefinitely and takes precedence even if timeout_ms is also supplied. Mob reads use the same flat fields with meerkat_mob_event_stream_read and the mob stream’s returned ID. The decoded read payload has one of three statuses:
A timeout leaves the handle open for the next read. Exhaustion returns closed and removes the handle; another read then fails as not found. Session and per-member reads carry an EventEnvelope<AgentEvent> directly under event. Omit member_id to open a mob-wide stream: its events are AttributedEvent values with member attribution and a nested envelope, so the agent payload is at event.envelope.payload instead of event.payload. Close a handle when finished:
For a mob handle, use meerkat_mob_event_stream_close with its stream_id. closed: true means this call removed the handle; false means it was already absent. Close results use a boolean, unlike a read’s status: "closed".

Tool reference

meerkat_run

Start a new Meerkat agent session with the given prompt.

Parameter reference

string
required
User prompt for the agent.
string | null
default:"null"
Override system prompt.
string | null
default:"config default"
Model name (e.g. "claude-opus-4-8", "gpt-5.5").
u32 | null
default:"config default"
Max tokens per turn.
string | null
default:"inferred"
Explicit MCP override vocabulary: "anthropic", "openai", "gemini", or "other". "self_hosted" is not an accepted explicit token here. Omission/null still permits configured model/binding resolution, including configured self-hosted routes; accepting "other" does not guarantee an operational custom provider.
WireAuthBindingRef | null
default:"null"
Optional structural credential selector, for example {"realm":"prod","binding":"anthropic","profile":"claude_oauth"}. realm and binding are required when supplied; profile is optional. Configure the referenced realm, binding, and auth profile first. Omission/null lets the create resolver select credentials. This is not a colon-delimited CLI string and does not accept server-owned provenance. It is a meerkat_run selector, not a new meerkat_resume field.
object | null
default:"null"
JSON schema for structured output (wrapper or raw schema).
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.
string | object | null
default:"null"
From 0.9.15. The session’s provider-neutral reasoning effort level (see Reasoning effort). On meerkat_run: none, minimal, low, medium, high, xhigh or max. On meerkat_resume: a level sets it from this turn on, {"action":"clear"} removes it, and omission keeps the level the session recorded. It is the same setting as provider_params.reasoning_effort; an input that gives both must ask for one outcome (refused as invalid params otherwise). A level the model or its route does not accept is refused before any provider request: the tool call fails with a typed tool error in the shape JSON-RPC uses, code -32602 (invalid params) with the data {"kind": "reasoning_effort_refused", "retryable": <bool>, "reasoning_effort_refusal": {...}} (see Reasoning effort refusal data). After a call created its session, the data also names the session (session_id, session_ref, session_created, resumable). Read the data, never the message. One case is not recognisable by its data kind: a meerkat_resume of, or a meerkat_comms_send to, the session of a mob member that is not live, when that member’s own build is refused for the level in its profile, answers the generic agent error (-32013) with a message that contains the refusal’s sentence and no reasoning_effort_refused data; a level the resume itself carries is judged after the wake and is answered by the typed refusal as everywhere else.A meerkat_resume that names the level (this field, set or clear, or the reasoning_effort key inside provider_params) rebuilds the session, and a rebuild can end a resume that was accepted behind a running turn. So while a turn is running on the session such a resume is not queued: the tool call fails at once with code -32002 (session busy) and the data {"kind": "reasoning_effort_change_needs_idle_session"}, the kind JSON-RPC answers such a turn with. Nothing is retired or stored, and the running turn and the resumes behind it go on. Wait for the running turn’s answer, then send the resume again; do not poll. When the running turn is not the caller’s (a peer message on a keep-alive session, a scheduled run) there is no answer to wait for: send the resume again later. This is the MCP server’s own rule, not the table of the JSON-RPC turn requests (Model settings on a busy session): it applies to every resume that names the level while a turn runs, whatever the session holds, a repeat of the session’s level and a clear on a session without one included. The level is judged when the session is rebuilt, so on a busy session a level the model does not accept is answered busy first, and its typed refusal when the resume is sent again. With no turn running the resume rebuilds the session at once. Two limits stay. A plain resume that starts between the server’s check and the level resume’s own start runs, but a request queued behind that plain resume can still be ended by the rebuild (read from the source, not run). And a plain resume sent at the same moment as a level resume, before either turn has started (also on a session that has no turn running), is answered Ok, with -32003 (session_resume_required), or with one of two errors that carry no kind: -32603 (Agent error: agent error: Internal error: Runtime not ready: destroyed) or -32005 (request cancelled). Whichever of these three comes, its prompt may have run all the same, and is then in the session’s history with the model’s answer once the level resume has answered. So after anything but Ok on a resume that was sent beside another resume: wait until the other resume has answered, read the session’s history (meerkat_history), and send the prompt again only if it is not there. A resume that rebuilds the session for another field (model, max_tokens, provider_params without the level, and the other build fields) is unchanged from 0.9.14: it waits behind the running turn, rebuilds the session and runs. A plain resume queued beside such a resume has the same answers, and the same advice holds.
bool
default:"false"
Stream agent events via notifications/message; see event streaming for the envelope and pull-stream tools.
bool
default:"false"
Enable verbose event logging (server-side).
array
default:"[]"
Tool definitions for the agent (see McpToolDef schema below).
bool | null
default:"null"
Builtins override. Omit / null to use the default on run or inherit the persisted session value on resume.
object | null
default:"null"
Config for builtins (only used when enable_builtins is true).
bool | null
default:"null"
Shell-tools override. Omit / null to use the default on run or inherit the persisted session value on resume.
u64 | null
default:"null"
Default command timeout, in seconds, of the shell tool in the session this call builds: the session’s own [shell] timeout_secs. A shell call’s own timeout_secs still wins. The session records it, so a meerkat_resume that rebuilds the session keeps it unless the resume sets its own. Omit / null / 0 keep the realm’s [shell] timeout_secs (30 s unless configured) on meerkat_run, and the session’s recorded value on meerkat_resume.
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.
string | null
default:"null"
Agent name for comms.
HookRunOverrides | null
default:"null"
Run-scoped hook overrides.

McpToolDef schema

string
required
Tool name.
string
required
Tool description.
object
required
JSON Schema for tool input.
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.
Decode the pending payload from content[0].text. It is a control result with status: "pending_tool_call", session_id, resumable: true, pending_tool_calls, and human-readable content, not a completed-run payload. A session_ref may be present when assigned by the surface; session_created: true, when present, says that the suspended request created the session (false is omitted). Do not infer successful-run counters from a pending result. Echo each provider-issued tool_use_id exactly in tool_results, as tc_abc123 is echoed above. Never correlate by tool name or array position, even when several pending calls invoke the same tool. Since 0.9.5 a pending call made in a run’s tool round also carries dedupe_key, an object with run_id, round, call_id and call_digest. After a restart, a durable run can suspend on the same call again, with the same key. A tool whose effect must not happen twice records the key with the effect and answers a repeat from that record; see Durable Runs: Tools That Run Again.

Parameter reference

string
required
Session ID to resume.
string
required
Follow-up prompt (can be empty when providing tool results).
bool
default:"false"
Stream agent events via notifications/message; see event streaming.
bool
default:"false"
Enable verbose event logging.
array
default:"[]"
Tool definitions (should match the original run).
array
default:"[]"
Tool results for pending tool calls.
string
required
Exact provider-issued tool_use_id from the matching pending call.
string
required
Result content (or error message).
bool
default:"false"
Whether this is an error result.
bool | null
default:"null"
Builtins override. Omit / null to inherit the persisted session value.
object | null
default:"null"
Builtin tool config.
bool | null
default:"null"
Shell-tools override. Omit / null to inherit the persisted session value.
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.
string | null
default:"from session"
Agent name for comms.
string | null
default:"from session"
Model override. On materialized sessions this hot-swaps the LLM client for the remainder of the session.
u32 | null
default:"from session"
Max tokens override.
string | null
default:"from session"
Provider override for mid-session switching with model: "anthropic", "openai", "gemini", or "other", as on meerkat_run. Omission/null permits normal model/binding resolution; "self_hosted" is not an accepted explicit token.
HookRunOverrides | null
default:"null"
Run-scoped hook overrides.
object | null
default:"null"
Per-turn tool overlay, the same shape turn/start takes: allowed_tools, blocked_tools, and tool_choice_plan (entry k is the tool choice of the turn’s k-th provider call, for example [{"mode": "required"}]). It applies to this turn only, on a live session and on a resume that rebuilds the session’s agent. Keys it does not know are ignored and logged by the server.

Response format

Both meerkat_run and meerkat_resume return MCP-standard tool results. Parse the JSON-encoded content[0].text payload. Completed runs contain the fields below; callback-pending control results use the distinct shape above.
array
MCP content blocks with the agent’s text.
string
Session ID (save for meerkat_resume).
u32
Number of LLM calls made.
u32
Number of tool calls executed.
JSON | null
Parsed structured output when extraction succeeds, or explicit null.
ExtractionError | null
Post-turn extraction failure details, or explicit null. The object has last_output (the committed main-turn assistant text extraction tried to transform), attempts (number of extraction attempts), and reason (human-readable failure description).
array | null
Schema compatibility warnings.
The main turn can successfully return committed text in content even if post-turn extraction fails. Inspect both structured_output and extraction_error; missing structured output does not prove extraction was never requested. Unlike REST/RPC WireRunResult, the MCP completed-run inner payload includes explicit null values for these absent optional fields; the outer MCP text wrapper remains unchanged.

meerkat_config

Get or update realm config for this MCP server instance.
string
required
One of "get", "set", "patch".
object | null
Full config to replace (for set action).
object | null
RFC 7396 merge-patch delta (for patch action).
u64 | null
Optional optimistic concurrency check for set and patch.
Response includes config envelope fields:
  • config
  • generation
  • realm_id
  • instance_id
  • backend
  • resolved_paths (only when the server runs with --expose-paths)
The MCP surface returns only the ConfigEnvelope shown above. It does not carry the live_propagation field: that is part of the richer JSON-RPC ConfigWriteResult contract, which reports the per-channel hot-swap / refresh / close outcome (swapped, skipped, swap_failed, refreshed, closed, refresh_failed, close_failed) when a set/patch write fans out to live channels. Use the JSON-RPC config/set / config/patch methods when you need the typed live-propagation report. A set or patch that would administer a section the host administers in the document itself is refused with -32602 (invalid params), and nothing is written. The error’s data.type is governance_administration_required (change, remove or restate [governance]) or confinement_administration_required (add, change or remove [confinement], or add a credential command or change what one runs). A write that changes realm sections (a parent edge, or the user document’s [realm.global]) so that a realm would compose a different section is refused with the same types, and its message names the change and the realm.

meerkat_capabilities

Returns the runtime capability set with status resolved against config.
Possible status values:

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.
string
required
"list" to list all skills, or "inspect" to load one skill’s full body.
object
Required for inspect. The typed skill identity with source_uuid and skill_name fields.
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.