MCP and integrations

AgentGrid 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 harness with master-MCP support gets a scoped MCP configuration at launch. AgentGrid passes that configuration to the selected harness using its native integration. Per master, the 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. list_roles entries include source: "builtin" | "custom".
• create_role — define a project custom role in .agent-grid/roles.json so spawn_role can use it. Built-in role names are immutable and always hard-reject, even with overwrite: true; that flag only replaces an existing custom role of the same name.
• 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 AgentGrid 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.
• AgentGrid 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, terminalAccess, writePathPrefixes, backend ('pty' or 'sdk').

Set terminalAccess: true only for roles that should be allowed to spawn and control visible terminal panes. AgentGrid enforces that role gate before terminal actions are dispatched, including when workers run through the background daemon.

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.