Workspace MCP Server
Agents use the workspace MCP server to inspect workspace state, create tiles, publish artifacts, and manage boards.
studio.* tools
Workspace context & notes
| Tool | What it does |
|---|---|
studio.get_workspace_context | Read the current workspace shape, including tiles and desktops. |
studio.get_workspace_notes | Read workspace-level free-text notes (full document — intended for read-then-rewrite-whole). |
studio.update_workspace_notes | Write workspace notes (PUT, not patch — supply the full new content). |
studio.git_log | Read the workspace repo’s commit history, newest first. |
studio.lane_retention | Explain why each lane in the workspace still exists — the lane cleanup’s last verdict per lane, such as unpushed commits, uncommitted work, or a tile or running card still using it. Read-only. |
Yolo Keeper notes
Durable, searchable notes shown in the Yolo Keeper app — the place for knowledge worth keeping about the repository.
| Tool | What it does |
|---|---|
studio.create_note | Create a note (title, optional body, tags, pinned, color). |
studio.list_notes | List notes without their bodies; active notes by default, or archived: true. |
studio.search_notes | Case-insensitive search over titles, bodies and tags; returns short excerpts. |
studio.read_note | Read one note in full by noteId. |
studio.update_note | Update a note. expectedRevision is required; a stale revision returns VERSION_CONFLICT with the current note instead of overwriting it. |
studio.archive_note | Archive a note, or pass archived: false to restore it. Notes can’t be permanently deleted through MCP. |
Desktop management
| Tool | What it does |
|---|---|
studio.create_desktop | Create a desktop in the workspace. |
studio.list_desktops | Enumerate all desktops in the workspace. |
studio.archive_desktop | Archive a desktop (hides from the switcher; tiles freeze in place). |
studio.delete_desktop | Permanently delete a desktop. Its pins close and its tiles move to main; main itself cannot be deleted. Restricted to User and Live Coding Agent roles. |
studio.pin_tile | Pin a tile across desktops as a live mirror — source and pin always show the same state. |
Tile management
| Tool | What it does |
|---|---|
studio.list_tiles | List all tiles on the workspace (or a specific desktop). Each preview tile carries preview.url and preview.status; once status is ready, pass the URL to studio.browser_navigate. |
studio.create_agent_tile | Create an agent tile with a specified agent binary, title, optional lane, and branch mode. |
studio.create_app_tile | Create an App tile for an installed app (call studio.install_app first). |
studio.create_preview | Create a preview tile for an approved port and optional saved-config source. |
studio.create_kanban_tile | Create a Kanban board tile and seed its board (default To do / Doing / Done, or supply columns); backgroundDrain also makes it the Background Runner’s source. Drive it afterward with the studio.kanban_* tools. |
studio.create_checklist_tile | Create a Checklist tile and bind its list — attach an existing listId or mint a fresh list (optionally name + seed items). Drive it afterward with the studio.checklist_* tools. |
studio.create_tile | Create a config-light, non-agent tile: terminal, pr-status, github-actions, content-drop, file-activity, background, pomodoro, or loop-designer (only when loops are enabled). pr-status reads config (repo as owner/repo; omit to auto-detect from the git remote) and loop-designer reads config.loopId to open an existing loop. |
studio.remove_tile | Remove a tile from the workspace and prune it from the layout tree. |
studio.read_tile_output | Read the latest output of an agent or terminal tile without typing into it. Read-only; never boots the agent. |
studio.resize_tile | Resize a tile within its split — size is a percentage of the tile’s immediate parent, like dragging the divider. |
studio.update_tile_status | Update constrained tile status fields (status, message, progress). |
studio.send_to_tile | Deliver a prompt into an agent or terminal tile, booting the agent if needed. Pass submit: false to leave the text unsent. |
studio.pin_tile | Pin a tile across desktops as a live mirror. |
Work Artifacts
| Tool | What it does |
|---|---|
studio.publish_artifact | Publish a typed (text/JSON) Work Artifact to the workspace artifact store, where other agents can read or wait for it. |
studio.get_artifact | Fetch an artifact by key, with optional version pin. |
studio.list_artifacts | List Work Artifacts in the workspace. |
studio.wait_for_artifact | Block until a named artifact appears (polling with timeout). Coordinates producer→consumer agent handoffs. |
File access
| Tool | What it does |
|---|---|
studio.list_files | List files under a path (relative to workspace root), BFS to a configurable depth. |
studio.read_file | Read a single file, up to a configurable limit (default 256 KiB, hard cap 1 MiB). |
studio.search_files | Search file contents using ripgrep with a fixed-string query. |
studio.open_file | Open a file in a file-viewer tile, or create one, with optional lane and desktop targeting. Pass readerMode: true for a distraction-free open — the file tree is hidden (re-expandable) and markdown renders as a formatted preview. |
studio.open_file_reader | Convenience preset — same as studio.open_file with readerMode: true always on (tree hidden, markdown rendered). Takes no boolean, for callers that prefer not to pass one. |
Preview tiles
| Tool | What it does |
|---|---|
studio.finalize_preview | Attach a command, cwd, env, readiness pattern, and framework to a preview tile’s saved config. |
studio.trigger_preview | Execute a preview tile’s finalized command (start or restart the dev server). |
studio.notify_preview_ready | Notify the platform that a preview server is ready on a port — finds and updates matching tiles. |
studio.inspect_port | Read-only: inspect what process holds a port. Returns a short-lived confirmToken. |
studio.reclaim_port | Kill the process occupying a port (using the token from inspect_port). Only reclaimable if attributable to your own lane. |
Stashes
The Stash is an operator-curated side surface. The agent-facing surface is intentionally narrow — three tools, all stash-scoped (studio.list_stashes / studio.read_stash / studio.save_to_stash):
| Tool | What it does |
|---|---|
studio.list_stashes | List Stash buckets in the workspace with clip counts and metadata (no clip bodies). |
studio.read_stash | Read clip contents from one bucket. Pages in display order with each body capped at 8,000 chars; pass clipId for one clip’s full body. Never creates a bucket. |
studio.save_to_stash | Save content into a Stash bucket (creates the bucket if it doesn’t exist). |
Kanban
Agent surface for the Kanban board tile. Mutations carry an agent audit trail (cards show who created or last touched them), and a delegated token narrowed to specific tiles can only mutate boards owned by those tiles.
| Tool | What it does |
|---|---|
studio.kanban_get_board | Read a tile’s board — columns and cards — by tileId or boardId. |
studio.kanban_update_board | Rename a board or update its column set (boardId, name, columns). |
studio.kanban_create_card | Create a card (boardId, columnId, title, and a required expectedOutput of code / workspace / report; optional description, key, dependencies, supersedes, requestId for idempotent retries). |
studio.kanban_update_card | Edit a card’s title, description, expectedOutput, or supersedes link (null clears it) — at least one is required. Moves are deliberately a separate permission. |
studio.kanban_move_card | Move a card to another column and/or position (cardId, columnId, order). |
studio.kanban_delete_card | Delete a card; the server scrubs it from other cards’ dependency lists. |
studio.kanban_add_dependency | Mark a card as blocked by another (cardId, blockedByCardId). Cycles are rejected (409 CYCLE_DEPENDENCY). |
studio.kanban_remove_dependency | Remove a blocked-by link between two cards. |
studio.kanban_start_board | Set up a board in one confirmed step: create or reuse the board, make it the Background Runner’s source, set where cards land and the landing policy (off / review / auto), place the Runner tile and a preview that follows the landing branch, and optionally start the Runner. Call it without confirm to get the plan, then again with confirm: true. |
studio.kanban_inspect_card | Inspect a card: status, review phase and verdict, executor and reviewer models, acceptance, and by default the worker transcript. compact: true drops the report text; includeOutput: false drops the transcript. Read-only. |
studio.kanban_wait_for_card | Wait up to 25 seconds for a card to reach a terminal result or a finished review phase. Read-only; call again after a timeout. |
studio.kanban_preview_revision | Preview a billed re-run of a completed card: its source, blockers, policy and cost implications. Read-only. |
studio.kanban_queue_revision | Queue that re-run once the owner has confirmed it. It dispatches a fresh, billed worker and moves the card back to Ready. |
studio.kanban_supersede_card | Mark a card’s unlanded result as replaced by another card on the same board. Owner-confirmed (confirmSupersede: true); nothing is retired until the replacement’s result has landed. |
studio.kanban_abandon_landing | Abandon a card’s unlanded code result: stop its landing, release its lane and optionally close its PR. Owner-confirmed (confirmAbandon: true). Dependents stay blocked. |
studio.kanban_release_card | Release one card’s Background Runner execution: stop its worker, or free its slot at once when no live worker exists. Other cards keep running. A live supervisor is never forced. |
studio.kanban_requeue_card | Queue a new attempt of a card that failed, was cancelled or was released, so the runner admits it again. Spends money like the original attempt. Refused for landed cards. |
Checklist tools
Agent surface for the Checklist tile — Keep-style per-workspace checklists. Lists outlive their tile (closing a tile detaches; re-attach by id), and a delegated token narrowed to specific tiles can only touch lists those tiles point at. There is deliberately no delete-list tool — archive via studio.checklist_update_list (hard delete is operator-only).
| Tool | What it does |
|---|---|
studio.checklist_list_lists | List the workspace’s checklists (summaries with item/checked counts; pass includeArchived for archived ones). |
studio.checklist_get_list | Read a full list — metadata + items — by listId. |
studio.checklist_create_list | Create a list (all optional: name, color, seed items, requestId for idempotent retries). |
studio.checklist_update_list | Rename, recolor, pin, or archive a list. |
studio.checklist_add_item | Append an item (listId, text). |
studio.checklist_update_item | Edit an item’s text only — checking and moving are separate permissions. |
studio.checklist_check_item | Tick or untick an item (listId, itemId, checked). |
studio.checklist_move_item | Reorder an item (order is a float — between neighbors is (a+b)/2). |
studio.checklist_delete_item | Remove a single item from a list. |
Apps
| Tool | What it does |
|---|---|
studio.list_apps | List curated and personal apps available to the caller (display names, descriptions, permission sets). |
studio.install_app | Record a grant for a tile app in the workspace (consent is recorded server-side). |
studio.create_app_tile | Add an installed app as a visible tile on the workspace grid. |
studio.create_personal_app | Create or update one of the caller’s personal apps with server-side manifest validation. |
YOLO Assistant-only tools
These two scopes are served to YOLO Assistant through its chat bridge only. They are not registered on the workspace MCP server, so coding agents cannot call them.
| Tool | What it does |
|---|---|
studio.annotate_tile | Record why a tile exists — durable purpose and associations — and optionally append a history note. |
studio.suggest_delegate_agent | Recommend a tier-compatible coding agent from the registry for delegation — returns a recommended agent plus fallbacks and the caller’s userTier. |
Goals and inbox tools
For goals linked to the agent’s workspace; see Goals.
| Tool | What it does |
|---|---|
studio.goal_get_context | Read the goals this workspace works toward: success checks, constraints, and the plan steps homed here. Pass your Kanban cardId to get the step your card is working on. |
studio.goal_record_evidence | Record a result or observation for a goal. It waits for the owner’s review — it never marks a goal achieved. Pass your cardId to deliver your step’s result. When the owner sent an earlier attempt back with notes, also pass answers and one responses entry per note (kept, fixed, removed, answered or declined, with an explanation and where to look). The owner sees your replies as your account and resolves each note. |
studio.goal_get_review | For a card answering the owner’s review: their guidance, every note with its id and full quote, the previous result, and the exact answers ids to reply with. |
studio.goal_report_progress | Tell the owner where your card’s plan step stands: working, blocked (also sent to their Inbox) or done. It never changes the step’s state, which follows the card. |
studio.goal_archive | Archive a goal linked to this workspace, only when the operator asked for it. Reversible by the owner. |
inbox.send | Send a markdown message to the workspace owner’s inbox — completion reports, summaries and updates, with links. Only ever reaches this workspace’s owner. |
yolo_background.* tools
Control the Background Runner.
| Tool | What it does |
|---|---|
yolo_background.get_state | Read the Runner’s state: whether it is on, its source board and columns, landing policy and capacity. |
yolo_background.configure | Preview, then apply, the Kanban board mapping, where lane PRs land, and the landing policy (off / review / auto). |
yolo_background.start | Start admission using the saved settings; optionally choose standing or drain-once mode. |
yolo_background.stop | Pause admission or request cancellation. Capacity stays held until workers stop. |
yolo_background.concurrency | Set how many cards run at once, from 1 to 4. |
yolo_background.force_release | Last resort for a Runner stuck in Cancelling after its sandbox died: releases capacity held by claims you already cancelled. |
yolo_background.routing_get | Read routing: whether it is on, Jev’s status and why it is unavailable, the model catalog, and the runner and board policies. |
yolo_background.routing_set | Preview, then apply, turning routing on or off. |
yolo_background.routing_decisions | Read recorded routing decisions for one card, or the latest across cards. |
yolo_background.routing_preview | Show where routing would send one card now. Read-only. |
yolo_background.routing_policy_set | Replace the runner’s or one board’s routing policy. |
yolo_background.routing_policy_delete | Delete a runner, board or card policy so it inherits again. |
loops.* tools
Available only where the deployment enables loops. See Loops.
| Tool | What it does |
|---|---|
loops.list_templates | List the curated loop starter configs (docs sweep, test coverage push, flaky test stabilizer, and others). Read-only. |
loops.create | Queue a loop: prompt, exit (mode all/any, 1–8 checks), maxIterations (1–25), carry (worktree/fresh); optional name, agent, onCapReached, retry, budget, noProgressWindow, baseBranch, requestId. Does not start the runner unless run: true; if that would also run Ready Kanban cards, it returns needs-kanban-confirmation — resend with confirmKanbanBacklog only after the operator agrees. |
loops.run | Launch a queued loop: turns on the loop source and starts a stopped runner. Uses the loops.control scope. |
loops.list | List loops (optionally by states) with the runner’s loop status. |
loops.get | Read one loop: state, iteration of cap, spend, and per-attempt decisions and check results. |
loops.control | pause, resume, cancel or raise-cap, fenced on generation / expectedConfigVersion from loops.get. |
Browser tools
The browser tools expose a Puppeteer-driven Chromium session that runs inside the workspace container. All tools below operate on a session id returned by studio.browser_create.
Session lifecycle
| Tool | What it does |
|---|---|
studio.browser_create | Open a headless or tile-rendering Chromium session. renderMode: "tile" requires initialUrl; renderMode: "headless" (default) starts blank. |
studio.browser_close | Close a session and drop its artifact footprint from R2. |
studio.browser_list | List all open browser sessions in the workspace’s session pod. |
studio.browser_attach_tile | Create or find an agent-browser-* tile and attach the session’s screencast to the workspace. |
studio.browser_attach_to_preview | Attach a browser session to a preview tile — polls for status === "ready" and resolves the URL automatically. |
Navigation & interaction
| Tool | What it does |
|---|---|
studio.browser_navigate | Navigate to a URL with optional waitUntil condition. |
studio.browser_click | Click a selector with optional button, click count, delay, and visibility requirement. |
studio.browser_type | Type text into a selector with optional delay and clearFirst. |
studio.browser_hover | Hover over a selector to trigger hover interactions. |
studio.browser_scroll | Scroll the page or a specific element. |
studio.browser_select | Select option values in a <select> element. |
studio.browser_wait_for | Wait for a selector, a predicate function, or networkIdle. |
studio.browser_upload | Upload an artifact file to a file input (up to 50 MiB). |
Inspection
| Tool | What it does |
|---|---|
studio.browser_state | Snapshot one session: current URL, title, viewport dimensions, busy state, last error. |
studio.browser_query | Query elements matching a selector and return matching nodes with optional attributes. |
studio.browser_evaluate | Evaluate a JavaScript expression in the page context (≤ 8 192 bytes). |
studio.browser_screenshot | Capture a full-page or viewport screenshot, upload to R2, return the artifact key. |
studio.browser_get_console | Return recent console messages from the session’s ring buffer with optional level/time filtering. |
studio.browser_get_network | Return recent network events from the session’s ring buffer. |
studio.browser_download_wait | Wait for the next download to complete and upload the bytes to R2. |
Tracing
| Tool | What it does |
|---|---|
studio.browser_trace_start | Start a Chrome DevTools trace with optional categories. |
studio.browser_trace_stop | Stop the active trace, upload the trace JSON to R2, return the artifact key. |
Scenarios
| Tool | What it does |
|---|---|
studio.browser_record_scenario | Run a scenario against a live session and capture network envelopes (200 interactions by default; maxInteractions sets 1–1000). |
studio.browser_replay_scenario | Run a scenario in replay mode against a captured envelope with request interception. |
studio.browser_run_scenario | Run a scenario, upload the resulting screenshots to R2, return artifact keys. |
studio.browser_diff_scenario | Compare two URLs side-by-side via scenario execution with artifact storage. |
studio.browser_save_state | Save browser auth state (cookies, localStorage) to an artifact, scoped to an origin. |
studio.browser_restore_state | Apply saved auth state to the live page, with origin enforcement. |
See Agent Browser for the user-facing guide on watching a browser session in a tile.
Adding MCP servers to your workspace
Beyond the built-in studio server, YOLO Studio ships a small catalog of additional MCP servers you can install per-workspace. Open Settings → MCP Servers and choose Browse and manage servers… to browse the catalog with live status (enabled / installed) and, for servers your operator has cleared for self-service, a toggle to install them into your workspace.
Enabling a server shows a short consent dialog describing what it does and what data it touches, then records the choice on your workspace. The server is installed and wired into your coding agents the next time the workspace starts — restart the workspace to begin using it. Disabling removes it from your selection the same way.
The first catalog server is Codebase Memory — a local knowledge-graph index of your repo (tree-sitter → SQLite) that gives agents structural code intelligence without scanning file-by-file. It runs entirely inside your workspace pod with no egress, and ships a graph visualization you can open as a tile from the same panel.
Why it matters
The server turns the workspace from a passive shell host into an agent-operable surface:
- Agents create UI objects the user can immediately inspect.
- Agents share durable workspace artifacts.
- Review Artifacts attach to the same workspace where the work happened, with provenance preserved.
Because tile creation changes the user-visible workspace, these calls should be used intentionally rather than speculatively.
See Concepts, Preview Tiles, and Agent Browser for more on workspace controls.
Last updated on