← All guides

MCP and integrations

The master's MCP tool surface, worker tools, and project-local role overrides.

Conceptual illustration of three braided cords with cobalt and ivory ceramic connectors joined at a brass hub.
AI-generated editorial illustration.
In this guide

AgentGrid is wired together through MCP — the master's surface for driving the canvas, the worker-spawned tools, and any third-party MCP servers a role configures.

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/video paths, note text, terminal scrollback, worker transcript).
  • send_to_pane({ paneId, message }) — deliver a message into an associated agent session pane (another master's live session), so two masters can collaborate. Same association gate as read_pane, cannot target your own pane. The delivered payload is wrapped in a fresh random-nonce fence — [message from master <sender paneId> · begin <nonce>]\n<body>\n[end <nonce>] — so the receiver can trust the outer attribution and treat the fenced body as untrusted content (the nonce is unforgeable per delivery). Only agent session panes accept messages.
Canvas-awareness sequence: list_canvas_panes finds a target, associate_pane opts in to its content, and read_pane reads the associated pane.

Listing a pane does not expose its content. The master associates the target pane before reading it.

Diagram by AgentGrid

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.
  • browser_navigate, browser_back, browser_forward, browser_reload, browser_read_page, browser_scroll, browser_screenshot — drive a pane you spawned or that the user attached.

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.

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.

Code
{
  "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": {
    "models": {
      "claude": "claude-opus-4-5",
      "codex": "gpt-5.6-sol"
    }
  }
}

Available fields: systemPrompt, allowedTools, disallowedTools, models, maxTurns, maxBudgetUsd, mcpServers, permissionMode, terminalAccess, writePathPrefixes, backend ('pty' or 'sdk'). The legacy singular model field remains supported for Claude-only roles.

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.