@polygraph/mcp

Polygraph MCP

A Model Context Protocol server for coordinating cross-repository changes via Polygraph.

Getting Started · Tools · Authentication · Learn More

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 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

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, 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):

• Environment variables — NX_CLOUD_AUTH_TOKEN or NX_CLOUD_ACCESS_TOKEN
• nx-cloud.env — Project-level env file
• nx.json — Project-level Nx configuration
• ~/.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