Tools

mcp.workbenches.dev serves 14 tools. Names follow the wb CLI. Every result has a short text summary for the model and structured content for programs. Each tool calls one or more public API routes with the caller's key.

search#

Search the registry for Workbenches your organization can run.

Returns workbenches, each with slug (org/name), org, version, summary, visibility, runner, model, runtime, runtimes, and sandboxed.

view#

Show what a Workbench packages. Read it before running one you have not used.

Returns workbench, workbench_id, version_id, version, description, runner, model, runtime, runtimes, requirements, sandboxed, skills, tools, mcps (names), env (names), required_env, workspaces (names), and visibility. A cloud run needs an organization secret for every name in required_env.

projects#

List projects with task counts. No parameters. Call it before tracked work and reuse an existing project.

Returns projects, each with name, slug, counts, and updated_at.

create_project#

Create a project, only after projects shows no existing or near-duplicate one.

Returns project.

workers#

List the organization's workers: members' machines that take runs instead of a cloud sandbox. No parameters.

Returns workers, each with slug (pass it to run as worker), name, shared, owner, os, cpus, memory_gb, gpus, runtimes (docker runs the Workbench's own image, local runs on the host), online, and slots (busy and total). A personal worker takes only its owner's runs.

run#

Start a run. It returns at once with a run ID and a session ID; the work continues in the background. Call wait next.

repository and ref must be given together, and branch needs both.

• Repository. With GitHub connected for the owner in the dashboard, the run can push its branch and open a pull request, public or private. Without a connection, a public repository clones anonymously and cannot be pushed to, and a private one cannot be fetched. The agent pushes to workbenches/<session id>, or workbenches/<branch> when branch is given, and opens the pull request itself when the task asks for one.
• Branch. One segment with no /, up to 100 characters, a valid git branch name of ASCII letters, digits, and ., _, -, not starting with wbs_. A run is refused with branch_in_use while another unfinished run of the organization uses the same branch of the same repository.
• Time. The organization's remaining sandbox time under its plan caps max_minutes further; a longer request is refused. The agent is told when its run stops.
• Worker. Worker time is free and uses no sandbox time. The worker must be online, shared or yours, and meet the Workbench's requirements, or the run is refused with the reason. It runs in the first runtime the Workbench declares that the worker offers, and waits for a free slot.
• Connection. Without it, a worker run uses the starting member's own sign-in on that worker and otherwise the organization's keys, and a cloud run uses the organization's OpenRouter key, the only connection a cloud run has. A run whose connection is unavailable fails with the reason before it starts.

Returns run_id, session_id, status, kind, and, on a worker, worker and runtime.

wait#

Block until a run needs you or ends, or wait on many runs at once. Pass exactly one of run_id, project, or run_ids.

With run_id, it returns when the run asks a question or requests a permission, when it completes, fails, or is cancelled, or when the timeout passes. New output and tool calls do not return it, so one call covers the stretch until the run needs you. A timeout with nothing new is rare and normal: call again.

The result is a digest, not raw events: the text the run wrote, the tools it used, and token and cost totals since after, plus next, the cursor to pass as after next time. A pending request comes with its request ID and what it asks. When the run produced an outcome, the result includes outcome_url, the API URL of a tar of the run's output files; downloading it needs the same bearer key (runs:read), and the URL is not signed. When the run has ended, it also returns the pull request the run opened or updated itself, if any (URL, number, and branch), and a summary of the files it changed. Use changes for the diff.

With project or run_ids, it returns attention:

• every run waiting on a question or permission, with the request ID and what it asks, listed on every call until you answer it,
• every run that completed, failed, or was cancelled since the previous call, with its final response, pull request, and changed files. The first call reports only runs that end after it starts.

It returns at once when attention is not empty, or when nothing in scope is running. Otherwise it blocks until a run needs you or ends, or the timeout passes. It also returns the IDs still running and a since cursor to pass back.

While blocked, it sends notifications/progress every 30 seconds when the client passed a progressToken, and it stops when the client cancels or disconnects.

changes#

Read the files a run changed in its repository.

Returns files with lines added and removed for each, the totals added and removed, the unified diff cut at 20,000 characters, and clipped when it was cut. A run that changed no files returns none.

send#

Give a run a message.

Returns run_id, command_id, kind, status (pending, claimed, delivered, or rejected), reason, and after, the cursor to pass to wait. A run that has ended cannot take a message: the result says the run already ended and to start a new run.

answer#

Reply to a question or permission request wait reported. It returns once the run has the answer, so the next wait does not report the same request.

Returns the same fields as send.

cancel#

Stop a run that has not finished.

If the run already ended, the result names its final status. Otherwise it returns the same fields as send; call wait with after to see it end.

runs#

List the organization's runs, newest first.

Returns runs, each with id, session_id, workbench, version, status, task (clipped), created_at, completed_at, usage, and project, and next when there is more.

sessions#

List the organization's sessions, newest first. A session groups the runs of one conversation with a Workbench.

Returns sessions, each with id, status, workbench_id, version_id, runner, model, runtime, workspace, latest_run_id, project, and updated_at, and next.

push#

Store a Workbench from text as a new internal version for your organization. It is not public.

A manifest missing name or instructions gets them filled in. Versions are immutable, so changed content needs a higher version in the manifest. A Workbench needs a sandboxed runtime to run in the cloud.

Returns reference (org/name@version), workbench, workbench_id, version, version_id, digest, and visibility.