MCP tools

The tool catalog for agents. MCP stdio and MCP over HTTP serve the same tools after initialize (protocol 2025-11-25).

A tool appears in tools/list only when the caller holds its capability. Argument names are camelCase.

The working loop

{"name": "workflow_start", "arguments": {"profile": "default", "url": "https://example.com"}}

workflow_start creates a session and a page, optionally navigates, and returns a workflowHandle plus sessionId, pageId and workflowId. Pass the handle to later calls instead of the IDs.

{"name": "workflow_observe", "arguments": {"workflowHandle": "wf_0123456789abcdef0123456789abcdef", "goal": "Find the sign-in button", "includeForms": true}}

workflow_observe returns retained context when it can answer goal, otherwise a live accessibility tree. Pass target: {"role": "main"} to skip site navigation. includeForms: true adds a form snapshot and needs page:read. The default evidenceDetail is compact; use full to debug.

Act with click, type_text, navigate, or an intent_* tool, passing the same handle. Close the session with session_close.

If workflow_start fails, it reports pageOpenFailed, navigationFailed, workflowGenerationChanged or workflowSupervisorLost, with cleanup fields (pageClosed, sessionDeleted, cleanupErrorCode). If the response may have been lost, call session_list before retrying.

Workflow handles

• A handle replaces sessionId and pageId on page-scoped tools. Do not send both: that is workflowBindingConflict.
• With exactly one live handle on the connection, a page-scoped call that names no scope uses it, and the evidence records workflowHandleDefaulted.
• page_activate with a handle and a pageId activates that page and rebinds the handle to it.
• After click_and_wait_for_popup, the handle follows the popup. If the popup later closes, read-only calls fall back to the opener page. Mutating calls fail with popupClosed evidence, so no effect is repeated.
• A handle is a convenience, not authority. Capability and ownership checks still apply. initialize invalidates all earlier handles. A malformed, unknown or expired handle is unknownWorkflowHandle; recover with explicit IDs.
• Streamable HTTP shares one server per principal, so a new initialize resets every handle of that principal. Use separate principals to isolate clients.

Tools

Parameters

Sessions and pages

executionPolicy flags are all off by default: javascriptEvaluation, visionAssist, fingerprint, humanize. visionNode names the vision node the session escalates to. zigzagzig: true creates a session with every flag on and automatic recovery; it is advertised only to principals holding browser:fingerprint and browser:humanize.

Reading a page

wait_for conditions are objects with a kind:

matcher is {"kind": "exact" | "contains" | "regex", "value": "..."}.

Acting on a page

click, type_text and upload_files take either a CSS selector or a target of the form {role, accessibleName, ordinal}. Pass snapshot targets unchanged.

download_url saves under the configured downloads directory. saveAs is relative to it or an absolute path inside it. The result echoes savedTo and a sha256, which is the proof of the saved bytes. maxBytes must be between 1 and the advertised maximum ([http].max_download_bytes). Text-like downloads also return downloadPreviews of up to 4 KiB.

selectOne and selectMany match an option's value first, then its visible label.

Boundary tools (click_and_wait_for_*, intent_follow with boundary, intent_submit_and_verify) accept autoCheckpoint to checkpoint around a page-changing step. click and the click_and_wait_for_* tools accept pinned commandId and attemptId.

Intents

Intent tools find controls by purpose and verify the result. Behavior and parameters are in Intent commands. All of them accept an optional idempotencyKey.

Recovery, events and jobs

See Events and recovery.

Toolsets

tools/list starts with the explore set to keep the handshake small. Hidden tools are still callable.

Choose the starting set with [mcp] startup_toolset or BOBBY_MCP_TOOLSET. Session and page lifecycle tools and toolset_select appear in every set.

Results and errors

A command whose outcome is not completed returns isError: true; check it before continuing. Failures carry a repair hint, error.repair for command failures and error.data.repair for protocol rejections, as {action, doc}. Every error message ends with the repair text.

An invalid call returns -32602 with data.reason:

Tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) let hosts gate calls. intent_submit_and_verify, intent_follow, session_close, page_close and cookie_delete are marked destructive.

Resources, prompts and notifications

Screenshots and downloads are readable as artifact://<id> resources when the caller holds artifact:capture. Screenshot results also include the image inline.

Prompts: start_browsing (optional url), fill_and_submit_form, extract_from_page and recover_workflow. The last three take sessionId and pageId; recover_workflow also takes workflowId.

After initialize the server pushes notifications/bobby/event for each runtime event of the caller and notifications/tools/list_changed when the caller's capabilities change. Over HTTP they arrive on the GET /v1/mcp stream.