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

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

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

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