MCP and integrations

Agent Grid is wired together through MCP — the master's surface for driving the canvas, the worker-spawned tools, and the third-party servers like Playwright that workers can opt into.

The master's tool surface

Every Claude master pane gets an MCP server materialised at launch and the claude CLI is spawned with --mcp-config <path> pointing at it. Per master, that surface is roughly ~40 tools grouped into four areas:

Canvas awareness

The master is blind to other panes until it opts in.

• list_canvas_panes — list every pane on the current canvas.
• associate_pane({ paneId }) / disassociate_pane({ paneId }) — opt in / out of seeing a pane's content.
• read_pane({ paneId }) — read an associated pane's content (image, code path, note text, terminal scrollback, worker transcript).

Worker lifecycle

• spawn_worker, spawn_role, list_roles — spawn a worker, by raw prompt or by a named role.
• send_to_worker — follow-up prompt to an existing worker (session is preserved via --resume).
• wait_for_worker, wait_for_any, read_worker_output — block on completion or peek mid-flight.
• list_workers, list_my_team — discover the workers / terminals / browsers this master owns.
• kill_worker, close_worker — interrupt a turn, with or without removing the pane.
• list_recoverable_sessions, resume_worker — re-attach orphan worker sessions after a master --resume.

See Orchestrating agents for the full review-loop pattern that uses these.

Terminals

• spawn_terminal({ command?, args?, initialCommand?, customTitle?, cwd? }) — open a long-running terminal pane.
• read_terminal_output({ paneId, sinceLine? }) — poll ANSI-stripped output with cursor-based pagination.
• wait_for_terminal_pattern({ paneId, pattern, flags?, timeoutMs }) — gate on a regex hit (great for dev-server readiness banners).
• read_dev_server_url({ terminalPaneId, timeoutMs }) — convenience layer that recognises Vite / Next / Astro / SvelteKit / Express / Fastify startup banners.
• send_terminal_input, kill_terminal — write raw bytes, or shut down.

Browsers

• spawn_browser({ url, customTitle?, cwd? }) — open an observable Chromium pane.
• read_browser, navigate_browser, wait_for_browser_navigation — read content, push the same pane forward, gate on navigation events.
• screenshot_browser, kill_browser — capture viewport, or shut down.

Auth

Every master gets a per-pane control token written into its MCP config (AGENT_GRID_CONTROL_TOKEN). The MCP stdio child uses that token to authenticate against the localhost HTTP control server the Electron main process runs. Tokens are scoped per master pane.

Playwright MCP for browser_qa

The browser_qa worker role pairs the Agent Grid browser MCP with @playwright/mcp so the worker gets a full Playwright tool surface inside the visible Chromium pane:

• Playwright tools: browser_navigate, browser_click, browser_fill_form, browser_snapshot, and the rest.
• Agent Grid browser tools: wait_for_user_input, request_user_login, highlight_element, save_recording, submit_findings.

The role is pinned to the SDK backend (PTY can't wire MCP servers into the interactive CLI), and write access is scoped to .agent-grid/qa-specs/ so recorded specs land in a predictable place. See Browsers for the user-facing flow.

Project-local .agent-grid/roles.json

Custom roles live in <projectDir>/.agent-grid/roles.json. The file is a Record<string, RoleConfig> that merges over the built-in roles at runtime — you can add new roles or override fields on existing ones.

{
  "design_reviewer": {
    "systemPrompt": "You are a Design Reviewer. Audit the diff against the design system. Report findings only — no code changes.",
    "disallowedTools": ["Write", "Edit"]
  },
  "qa": {
    "model": "claude-opus-4-5"
  }
}

Available fields: systemPrompt, allowedTools, disallowedTools, model, maxTurns, maxBudgetUsd, mcpServers, permissionMode, browserAccess, writePathPrefixes, backend ('pty' or 'sdk').

See Reference → Roles for the field-by-field reference and the full built-in role table.

Related

• Orchestrating agents — the spawn / wait pattern using the worker lifecycle tools.
• Browsers — browser_qa and the observable browser surface.
• The .agent-grid/ folder — all project-local conventions in one place.