# 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. | Tool | Does | API route | | ----------------------------------- | --------------------------------------------------- | --------------------------------------------- | | [`search`](#search) | Find Workbenches by text. | `POST /v1/searches` | | [`view`](#view) | Show what a Workbench packages. | `POST /v1/resolutions` | | [`projects`](#projects) | List projects and task counts. | `GET /v1/projects` | | [`create_project`](#create-project) | Create a project. | `POST /v1/projects` | | [`workers`](#workers) | List the organization's workers. | `GET /v1/workers` | | [`run`](#run) | Start a run. | `POST /v1/runs` | | [`wait`](#wait) | Block until a run needs you or ends. | `GET /v1/runs/:id/events`, `GET /v1/realtime` | | [`changes`](#changes) | Read a run's file changes and diff. | `GET /v1/runs/:id/changes` | | [`send`](#send) | Message a run. | `POST /v1/runs/:id/commands` | | [`answer`](#answer) | Reply to a question or permission. | `POST /v1/runs/:id/commands` | | [`cancel`](#cancel) | Stop a run. | `POST /v1/runs/:id/commands` | | [`runs`](#runs) | List runs. | `GET /v1/runs` | | [`sessions`](#sessions) | List sessions. | `GET /v1/sessions` | | [`push`](#push) | Store a Workbench from text as an internal version. | `POST /v1/versions` | ## search Search the registry for Workbenches your organization can run. | Parameter | Type | Default | Meaning | | ---------- | --------------------------- | -------- | --------------------------------------------------------------------------------------------- | | `query` | string, 1 to 120 characters | required | Free text to search names and summaries for. | | `limit` | integer, 1 to 50 | 10 | Most results to return. | | `runnable` | `cloud` or `any` | `cloud` | `cloud` returns only Workbenches that run in a cloud sandbox. `any` includes local-only ones. | 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. | Parameter | Type | Meaning | | ----------- | ------ | --------------------------------------- | | `workbench` | string | `org/name`, such as `acme/code-review`. | 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. | Parameter | Type | Meaning | | --------- | -------------------------- | ----------------- | | `name` | string, 1 to 64 characters | The project name. | 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. | Parameter | Type | Meaning | | ----------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `workbench` | `"org/name"` or `{ "version_id": "" }` | Required. `org/name` runs its latest version; `version_id` runs one exact version. | | `task` | string, 1 to 100,000 characters | Required. What the run should do. | | `project` | string | An existing project name or slug to track the work in. | | `repository` | string, `owner/name` | A GitHub repository to give the run as its workspace. Requires `ref`. | | `ref` | string | The branch, tag, or commit of `repository`. Requires `repository`. | | `branch` | string | Names the branch the run pushes: `workbenches/`. Requires `repository`. | | `max_minutes` | integer | How long the run may last. Defaults to 60, at most 1440. | | `worker` | string | A worker slug from `workers`, to run on that machine instead of a cloud sandbox. | | `connection` | string | Override the model provider connection, such as `openrouter` or `anthropic`. | | `session_id` | string, `wbs_...` | A session to continue. Continuing a session in the cloud is not supported yet, so a run with this set fails with that reason. | | `idempotency_key` | string, 1 to 200 characters | Repeating a key returns the original run. A random one is used when omitted. | `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/`, or `workbenches/` 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`. | Parameter | Type | Default | Meaning | | ----------- | ----------------------- | ------- | ------------------------------------------------------------------------------------------------------- | | `run_id` | string, `wb_...` | | One run. | | `project` | string | | A project's runs, by name or slug: its 50 newest, including runs started while waiting. | | `run_ids` | list of 1 to 50 run IDs | | These runs. | | `after` | integer, at least 0 | 0 | With `run_id`: the event cursor. Pass `next` from the previous wait, or 0 for the start. | | `since` | string | | With `project` or `run_ids`: the `since` cursor from the previous wait. Leave it out on the first call. | | `timeout_s` | integer, 1 to 3600 | 900 | Seconds to wait. | 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. | Parameter | Type | Meaning | | --------- | ---------------- | -------- | | `run_id` | string, `wb_...` | The run. | 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. | Parameter | Type | Default | Meaning | | --------- | ------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `run_id` | string, `wb_...` | | The run. | | `text` | string, 1 to 100,000 characters | | The message. | | `mode` | `send`, `steer`, or `queue` | `send` | `send` starts a new turn when the runner is idle. `steer` adds to the turn in progress. `queue` runs the message as the next turn, at once when idle. | 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. | Parameter | Type | Meaning | | ------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `run_id` | string, `wb_...` | The run. | | `request_id` | string, 1 to 200 characters | The pending request's ID, from `wait`. | | `response` | string, or a list of lists of strings | For a permission: `allow`, `deny`, or an offered option. For a question: a free text answer, or one list of chosen option labels per question, such as `[["Yes"]]`. | Returns the same fields as `send`. ## cancel Stop a run that has not finished. | Parameter | Type | Meaning | | --------- | ---------------- | ---------------- | | `run_id` | string, `wb_...` | The run to stop. | 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. | Parameter | Type | Default | Meaning | | ------------ | ----------------- | ------- | ------------------------------------------- | | `project` | string | | Only runs in this project, by name or slug. | | `session_id` | string, `wbs_...` | | Only runs in this session. | | `status` | run status | | Only runs with this status. | | `limit` | integer, 1 to 100 | 25 | Most runs to return. | | `cursor` | string | | `next` from a previous call. | 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. | Parameter | Type | Default | Meaning | | --------- | ----------------- | ------- | ------------------------------ | | `project` | string | | Only sessions in this project. | | `limit` | integer, 1 to 100 | 25 | Most sessions to return. | | `cursor` | string | | `next` from a previous call. | 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. | Parameter | Type | Meaning | | -------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | The registry name, lowercase words joined by dashes. Stored as `/`. | | `manifest` | YAML text or an object | The manifest. It needs `spec`, `version`, `runner`, `model`, and either `runtime` (spec 0) or `runtimes` (spec 1). The API validates it. | | `instructions` | string | The instructions, as text. Stored at the path the manifest names in `instructions`, or `instructions.md`. | | `files` | map of path to text | Extra text files, such as `skills/review/SKILL.md`. It cannot include `workbench.yml` or the instructions path. | 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`.