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)
Themeerkat-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.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)
CLI configuration (recommended)
Use therkat 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
Config file examples
Config file examples
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.
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 typedAuthorizationRequired 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 needsauth/logoutfirst.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_idis always absent and status reportsaccount_verification: "unverified"(host UI should say “account not verified”). No account strategy runs, and a re-login over an existing credential needsauth/logoutfirst.
mcp.toml(rkat mcp add --oauth-accountor--oauth-account-selection), or the host’s RPC and RESTmcp/add. Themeerkat_mcp_addmanagement 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 tounverifiedor to an unselected credential. A selected server must use streamable HTTP without a staticAuthorizationheader and a host OAuth resolver. Mob portable profiles cannot carryoauth_account_selectionand refuse it. Credentials live in the host’s token store, one per installation (forrkat, 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, whichrkatand 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 requestsopenid, calls the issuer’suserinfo_endpointwith the new access token and reportssub, which must equaloauth_accountwhen 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 ownMcpOAuthAccountStrategy. 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 reasonsaccount_selection_required(no selection) andverification_unavailable(no account evidence); neither ever switches the server tounverified, so a host offers that mode only as the operator’s explicit choice.rkat mcp loginprints the exactrkat mcp removeandrkat mcp addcommands 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’s401challenge names (itsscope), or else the resource metadata’sscopes_supported, in addition to the account strategy’s own; the completion is refused unless all of them are granted.offline_accessis 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
401fails with the typedAuthorizationRequiredstatus. Neither is replayed. A customMcpAuthResolvermust commit the credential itsinteractive_loginreturns, so thatstored_bearer_tokenreturns it from then on. -
Embedding hosts use
HostAuthService::mcp_login_startandmcp_login_complete(andmcp_login_cancelon 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_statusreports the attempt pending for a server by a non-secret reference, whichmcp_login_cancel_by_attempt_refcancels, andmcp_logoutretires any pending attempt and removes the server’s stored credential, so a callback admitted before the logout cannot store one.AgentFactory::mcp_auth_resolver(orAgentBuildConfig::mcp_auth_resolver) connects agents to those credentials. Runtime-backed RPC, REST and MCP-server hosts install this resolver by default, including for livemcp/addservers. -
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_loginbinds the loopback callback for you; its pending login has a typedcancelthat 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/canceland (RPC)auth/status/getwith an MCP target instead of a provider binding:redirect_urimust be an http loopback URL, or the host’s registeredhttpscallback (next item). Completion sends only the callback’scodeandstate(and the sameredirect_uri): issuer, client and resource come from the admitted attempt, and nothing network-facing happens untilstateis 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/getreports it asattempt: {ref, phase: "pending", expires_at}. Therefis not secret and grants nothing: a host that no longer holds the state (for example after its own restart) cancels with{mcp, attempt_ref}. RPCauth/logoutwith{mcp}retires any pending attempt and removes the server’s stored credential (nothing is revoked at the provider). Status and completion reportaccount_verification(verified,unverifiedorlegacy). The server must be configured (project or usermcp.tomlof the host):server_urlmust equal its configured URL, andoauth_accountoroauth_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
httpsredirect). A host whose users’ browsers cannot reach its loopback address (a server-hosted app) serves its ownhttpscallback endpoint and configures its base as host configuration:rkat-rpc --mcp-oauth-redirect-base https://host.example/mcp/oauth/callback, orHostAuthService::with_mcp_registered_redirect_basein 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/startwithredirect_uriset to the base (or to that server’s derived redirect) starts on it and adds two fields:host_attempt_handleis a secret: the host keeps it server-side with the ceremony it started, keyed bystate, and never puts it in the browser, a URL, a model, a transcript or a log.attempt_refis the public referenceauth/status/getreports; it authorizes nothing. Dynamic registration registers a public PKCEwebclient 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 callauth/login/completeonce:redirect_urimust 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 advertisesauthorization_response_iss_parameter_supported. A completion without the handle, with another one, or through a loopback-only path is refused (error.data.reasoninvalid_target,error.data.detailremote_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 andrkat mcp loginserve 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_enteredforms;mcp_client_profilereads it back without the secret). AnMcpOAuthClientProfilenames the authorization server’s issuer, the client id, the client’s exact registered redirect and its token endpoint authentication,client_secret_basicorclient_secret_post, with the client secret. The redirect is the host’s registered base itself (the central callback, below), the server’s own registeredhttpscallback (the base followed by the slot’s binding segment), or anhttploopback redirect on127.0.0.1orlocalhostwith an explicit port. A registeredhttpsredirect 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_urianswers 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_scopesrequests (and requires) the scopes the client is registered for in place of the ones the server names (offline_accessis never required), andwith_resourceaccepts 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 ashttps://host.example/services/mcp/callbackstays exactly that, with no slash added or removed. The slots’ attempts are told apart only by theirstateandhost_attempt_handle, so the host must route each callback by itsstateto the ceremony it retained when it started the login (the target and itshost_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: astatethat is not an attempt of that slot (attempt_missing) and a handle that is not that attempt’s custody (invalid_target, detailremote_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 anhttpsissuer, the token endpoint its metadata names, where the secret is sent, must usehttpsas well, loopback included, or discovery refuses it (upstream_failure) and nothing is sent there; only anhttploopback 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 throughmcp_begin_loopback_loginbinds 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 asreauth_requiredand the credential removed, so the user logs in again. Removal is not a revocation: the current access token stays usable until it expires, andmcp_statusreports the credentialAuthorizeduntil the refresh that ends it. To stop its use at once, callHostAuthService::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 exampleinvalid_clientfor 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, andmcp_statuscan keep reportingAuthorized, 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_enteredforms 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 orDebugoutput. 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 anAdministeringPrincipal, a qualified principal and optionally the digest of their login, and the host’sAdministrationRecorder). When the update settles, its owner hands the recorder oneAdministrationRecord: 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_enteredforms 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.reasonupstream_failureanderror.data.detailupstream_timeout(the authorization code had not been sent) orupstream_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/cancelbystateorattempt_ref, or a logout) while itsauth/login/completeis in flight ends that call at once withattempt_missing, andcancelled: truemeans nothing from that attempt is ever published. A cancel answeredattempt_missingwhile 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.reasoncommit_unsettled. Whether that credential landed is unknown until the commit settles; readauth/status/getlater. It is neither a success nor a failure. A commit that fails after it consumed the attempt and cannot restore the previous credential also answerscommit_unsettled; if a call to that server is then refused for authorization, log in again. A completion answeredcredential_access_pendingwas 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 callsmeerkat::settle_in_flight_credential_mutationsand, once it answersSettled, readsHostAuthService::mcp_status, which reports what a use of the stored credential would do. An embedding host sets the bounds withHostAuthService::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.reasonupstream_failure, the account preflight withverification_unavailable, and the error names none of the document’s content. Nothing is published.
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 themeerkat_* 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: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:
--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):
[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’snotifications/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
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
Setstream: true on meerkat_run or meerkat_resume:
tools/call request
notifications/message messages while the
request runs:
Push notification
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 viatools/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:
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:
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:
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
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.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.Max retries for structured output validation. Omit /
null to use the product default on run or inherit the persisted session value on resume.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.Stream agent events via
notifications/message; see
event streaming for the envelope and pull-stream tools.Tool definitions for the agent (see McpToolDef schema below).
Builtins override. Omit /
null to use the default on run or inherit the persisted session value on resume.Shell-tools override. Omit /
null to use the default on run or inherit the persisted session value on resume.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.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.McpToolDef schema
When tools withhandler: "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 samesession_id that meerkat_run originally materialized.
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
Stream agent events via
notifications/message; see
event streaming.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.Model override. On materialized sessions this hot-swaps the LLM client for the remainder of the 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.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
Bothmeerkat_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.
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).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.configgenerationrealm_idinstance_idbackendresolved_paths(only when the server runs with--expose-paths)
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.status values:
meerkat_models_catalog
Return the curated model catalog with provider profiles, capability metadata, and parameter schemas.meerkat_skills
List available skills with provenance information, or inspect one skill’s full body by typedSkillKey.
Optional source UUID selector for
inspect; omit it to load the canonical
source for skill_key.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.