Overview

Polygraph MCP enables AI coding agents to orchestrate synchronized changes across multiple repositories. It connects to Polygraph to manage sessions where a parent agent can delegate work to child agents in dependent repos, push branches, create linked pull requests, and monitor CI — all through a standard MCP interface.

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 Nx AI Agent Skills plugin, which includes Polygraph skills, subagents, and the MCP server pre-configured. Add this to your project's .claude/settings.json:

{
  "enabledPlugins": {
    "polygraph@nx-claude-plugins": true
  },
  "extraKnownMarketplaces": {
    "nx-claude-plugins": {
      "source": {
        "source": "github",
        "repo": "nrwl/nx-ai-agents-config"
      }
    }
  }
}

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 Nx AI Agent Skills for Polygraph 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 | | list_sessions | List existing Polygraph sessions | | add_repo | Add repos to a running session | | link_session | Link one session to another session | | complete_session | Mark a session as complete |

Agent Delegation

| Tool | Description | | ------------- | ---------------------------------------------------- | | spawn_agent | Delegate tasks to child agents in other repositories | | show_agent | Monitor status and output of delegated tasks | | stop_agent | Cancel an in-progress delegated task |

Git & Pull Requests

| Tool | Description | | --------------- | ---------------------------------------------- | | push_branch | Push a local branch to its remote | | create_pr | Create draft PRs with session metadata linking | | mark_pr_ready | Transition PRs from draft to open | | associate_pr | Link an existing PR to the session |

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, plan, 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 — Learn about coordinated cross-repo changes
• Model Context Protocol — The open standard for AI tool integration
• Autonomous Agents at Scale — How monorepo architecture enables autonomous AI agents

License

MIT