Overview

Polygraph MCP connects AI coding agents to Polygraph, the meta-harness for maximum agentic autonomy. It works with the agents you already use and gives them what they're missing: visibility across every repo boundary, and memory that survives every session. Through a standard MCP interface, agents discover how repositories relate, coordinate synchronized changes across them — delegating work to child agents in dependent repos, pushing branches, creating linked pull requests, and monitoring CI — and hand off or resume sessions later with repos, branches, PRs, and logs all preserved.

Getting Started

Prerequisites

• An account with Polygraph enabled
• Authentication credentials (see Authentication)

Installation

Claude Code (with Polygraph plugin)

The recommended way to use Polygraph with Claude Code is via the Polygraph plugin, which includes Polygraph skills, subagents, and the MCP server pre-configured. Add this to your project's .claude/settings.json:

{
  "enabledPlugins": {
    "polygraph@polygraph-plugins": true
  },
  "extraKnownMarketplaces": {
    "polygraph-plugins": {
      "source": {
        "source": "github",
        "repo": "nrwl/polygraph-skills"
      }
    }
  }
}

MCP server only

If you just need the MCP server without the full plugin, add it to your .mcp.json:

{
  "mcpServers": {
    "polygraph": {
      "command": "npx",
      "args": ["-y", "@polygraph/mcp@latest"]
    }
  }
}

Other AI agents

For Cursor, GitHub Copilot, Gemini, and other AI coding assistants, see the Polygraph plugin for skills and configuration tailored to each platform.

Tools

Polygraph MCP exposes authentication and workflow tools for managing cross-repository changes:

Authentication

| Tool | Description | | ---------------- | -------------------------------------------------------------- | | whoami | Show current auth status and selected organization | | login | Authenticate with either a token or the default CLI login flow | | logout | Clear locally stored Polygraph credentials | | list_accounts | List organizations available to the current user | | select_account | Select the organization to operate on |

Session Management

| Tool | Description | | ------------------ | --------------------------------------------------------------------------------- | | list_repos | Discover available repos and their dependency relationships | | start_session | Initialize a new Polygraph session | | show_session | Retrieve session details, status, and linked PRs with CI and merge-conflict state | | get_session_logs | Retrieve the parent agent transcript only (complete by default) | | list_sessions | List existing Polygraph sessions | | search_sessions | Search Polygraph sessions by free-text query | | add_repo | Add specific repository refs directly to a running session | | link_reference | Link an external reference to a session | | update_session | Update the session title and/or description timeline | | archive_session | Archive a session |

get_session_logs accepts optional tail and page values for pagination. When both are omitted, it returns the CLI's complete parent transcript JSON. It does not request child repository transcripts.

Artifacts

| Tool | Description | | ----------------- | ------------------------------------------------------------------------------------- | | upload_artifact | Attach a plan document, review report, image, or file to a session (or add a version) | | list_artifacts | List a session's artifacts with their kinds and versions | | delete_artifact | Permanently delete an artifact and all of its versions from a session |

Agent Delegation

| Tool | Description | | ------------- | ------------------------------------------------------------- | | spawn_agent | Delegate a task to a child agent; returns a delegation id | | show_agent | Check a delegation's status, or read the child's final result | | stop_agent | Cancel an in-progress delegated task | | allow_agent | Grant a child agent's pending permission-required request | | deny_agent | Deny a child agent's pending permission-required request |

Each of these tools accepts an optional role parameter, enabling multiple agents per repository. Omitting role targets the repo's default-role agent — the pre-role single-agent behavior, and the only role whose logs are uploaded/multiplexed to the cloud. Non-default agents are viewable locally via polygraph agent attach <repo> --role <role>.

Delegation ids

spawn_agent returns a short delegation id — frontend-1, frontend-2, … — built from the repo's short name plus a per-repo sequence. That id is the handle for the whole lifecycle: pass it to show_agent or stop_agent as id instead of repo/role, which it pins on your behalf. The two addressing modes are mutually exclusive; passing both is an error rather than a silent preference.

Spawning again for a repo+role whose task is still live delivers a follow-up to that task rather than starting a second run. The follow-up gets its own new id, with continues naming the one before it, so each turn stays addressable.

The intended flow:

1. spawn_agent → returns frontend-1.
2. Launch a polygraph-delegate-subagent with just that id. It calls show_agent in a loop with waitForTransitionMs set and no sleeps.
3. When it reports the task finished, call show_agent with id: "frontend-1" and no waitForTransitionMs to read result — the child's final message for that turn.

Batch delegation

spawn_agent starts several agents in one call, and show_agent takes an ids array to read several delegations in one call. Both are mutually exclusive with their single-agent inputs.

There are two forms of batch spawn, picked by whether the repos need the same work:

• repos — the same task in each of several repos. One instruction, written once, plus whichever of context, agent, model, and role apply to all of them. This is where the saving is: the instruction is one string rather than one per repo. A single-entry repos runs exactly what the scalar repo form runs.
• specs — a different instruction per repo. The brief they share goes in sharedInstruction (and sharedContext), with only the repo-specific half in each entry's instruction. The CLI joins shared text first, so siblings share one identical prompt prefix and read the same server-side cache entry instead of each writing their own.

repos is mutually exclusive with repo and with specs.

The response carries one result per repo, in request order, each with its own success. The call succeeds as a whole whenever the batch ran, so an entry can fail inside a successful response.

The CLI staggers a batch internally — the first agent runs alone for a moment so the rest read its prompt-prefix cache entry rather than each writing their own. There is no knob for it, and this server mirrors the same delay on the compatibility path where it has to spawn one agent per repo against an older CLI.

A batch read returns one children[] entry per requested id, in request order, each stamped with delegationId. An entry that could not be read (unknown id, repo no longer in the session) carries error; its status is failed like any other terminal child, so error is what separates a failed read from a child that ran and failed. A batch read never waits, so waitForTransitionMs is rejected alongside ids rather than applied to an arbitrary one of them.

On a CLI that predates either batch flag, the server fans the call out to N single calls and merges them into the same response shape.

Waiting vs. reading

A waited call (waitForTransitionMs > 0, max 300000) blocks server-side and returns the moment the child changes state, so a monitoring loop needs no sleeps. It is always status-only — no lastOutputLines, no result, even when the status it returns is terminal. The polling subagent never needs the child's words, and shipping them on every poll is what made this expensive.

An unwaited call returns result once the delegation's turn has ended. result.text longer than 10000 characters is truncated from the front, keeping the end, prefixed with [truncated — first N chars elided]; a child's conclusions are written last. tail and page read raw log lines instead — page walks backwards through tail-sized windows from the newest — and are rarely needed; the CLI already returns a single line by default.

The ceiling is 300000 ms for clients known to tolerate a five-minute blocked tool call (claude-code, opencode), and 50000 ms for any other client — including codex, whose per-call tool_timeout_sec defaults to 60s and can only be raised in the user's own ~/.codex/config.toml. That keeps the call under the MCP SDK's 60s default request timeout. Set POLYGRAPH_MCP_MAX_WAIT_MS to override both; a value that is not a positive integer is ignored.

Git & Pull Requests

| Tool | Description | | --------------- | ----------------------------------------------- | | push_branch | Push a local branch to its remote | | create_pr | Create draft PRs with session metadata linking | | update_pr | Update PR titles, bodies, labels, and assignees | | mark_pr_ready | Transition PRs from draft to open | | associate_pr | Link an existing PR to the session |

For update_pr, omitted fields remain unchanged. Collection mode set replaces all labels or assignees, and set with [] clears that collection. Use add or remove to preserve unrelated or human-applied values.

CI Integration

| Tool | Description | | ------------- | ---------------------------------------- | | get_ci_logs | Retrieve logs for GitHub Actions CI jobs |

Resources

Polygraph MCP exposes repositories and recent sessions as MCP resources, which compatible clients (e.g. Claude Code) surface as @-mention completions.

| URI | Content | | ----------------------------------- | ----------------------------------------------------------- | | polygraph://repos/<repo-id> | Repository metadata as JSON | | polygraph://sessions/<session-id> | Session details (status, description timeline, PRs) as JSON |

Only sessions created within the last 30 days are registered (server-side filter via --since and --limit=100 on the underlying polygraph session list call).

Authentication

Polygraph MCP resolves credentials from the following sources (in priority order):

1. Environment variables — NX_CLOUD_AUTH_TOKEN or NX_CLOUD_ACCESS_TOKEN
2. nx-cloud.env — Project-level env file
3. nx.json — Project-level Nx configuration
4. ~/.nxcloud.ini — User-level configuration (or XDG config path)

login accepts an optional token. When a token is provided it uses headless login; otherwise it runs polygraph auth login --json and relies on the CLI's default auth flow.

Learn More

• Polygraph — The meta-harness for maximum agentic autonomy
• Model Context Protocol — The open standard for AI tool integration

License

MIT