P4 Plan MCP Server

Architecture

This service acts as a stateless protocol adapter between MCP clients (AI assistants) and the P4 Plan GraphQL API, using stdio transport (stdin/stdout).

┌─────────────────┐     stdio (stdin/stdout)    ┌─────────────────┐     GraphQL      ┌─────────────────┐
│   AI Client     │  ────────────────────────▶  │  P4 Plan MCP    │  ──────────────▶ │ P4 Plan GraphQL │
│(Claude, Copilot)│   Spawns as child process   │    Server       │    Port 4000     │      API        │
│                 │   P4PLAN_API_AUTH_TOKEN     │   (stateless)   │  Bearer token    │                 │
└─────────────────┘          env var            └─────────────────┘  forwarded       └─────────────────┘

The client spawns the MCP server as a child process. Authentication is provided via the P4PLAN_API_AUTH_TOKEN environment variable, which the server validates at startup and forwards to the GraphQL API on every tool call.

Related MCP server: OpenProject MCP Server

Prerequisites

Tip: Use nvm to manage Node.js versions, or skip the Node.js requirement entirely by using Docker.

Quick Start (npx)

The fastest way to get started — no installation required. Just configure your MCP client to use npx:

npx -y @perforce/p4plan-mcp

npx automatically downloads and runs the latest version of the server. Your MCP client (VS Code, Claude Desktop, etc.) handles this for you — just add the config below and start chatting.

VS Code — add to .vscode/mcp.json:

{
    "servers": {
        "p4-plan": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "@perforce/p4plan-mcp"],
            "env": {
                "P4PLAN_API_AUTH_TOKEN": "YOUR_JWT_TOKEN",
                "P4PLAN_API_URL": "http://localhost:4000"
            }
        }
    }
}

Claude Desktop — add to your config:

{
  "mcpServers": {
    "p4-plan": {
      "command": "npx",
      "args": ["-y", "@perforce/p4plan-mcp"],
      "env": {
        "P4PLAN_API_AUTH_TOKEN": "YOUR_JWT_TOKEN",
        "P4PLAN_API_URL": "http://localhost:4000"
      }
    }
  }
}

Note: The -y flag auto-confirms the npm install prompt so the server starts without user interaction.

See Client Configuration for more options including Docker, secure token prompts, and local builds.

MCP Registry

This server is published to the official MCP Registry as io.github.perforce/p4plan-mcp. Discover it via the registry API:

curl 'https://registry.modelcontextprotocol.io/v0/servers?search=io.github.perforce/p4plan-mcp'

MCP clients that support registry discovery can install the server by name without needing to know the npm package identifier.

Installation

For development or when you want to run from a local clone:

npm ci
npm run build

# For using npx locally
npm link

Run the MCP server via Docker instead of installing Node.js locally. The MCP client (VS Code, Claude Desktop) spawns the container as a child process — same as npx, just using docker as the command.

The image is published to Docker Hub at perforce/p4plan-mcp, built multi-arch (linux/amd64 + linux/arm64) on every release, with SLSA provenance and SBOM attestations.

VS Code (.vscode/mcp.json):

{
    "servers": {
        "p4-plan": {
            "type": "stdio",
            "command": "docker",
            "args": [
                "run", "-i", "--rm",
                "-e", "P4PLAN_API_AUTH_TOKEN=YOUR_JWT_TOKEN",
                "-e", "P4PLAN_API_URL=http://host.docker.internal:4000",
                "perforce/p4plan-mcp:latest"
            ]
        }
    }
}

Claude Desktop:

{
  "mcpServers": {
    "p4-plan": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "P4PLAN_API_AUTH_TOKEN=YOUR_JWT_TOKEN",
        "-e", "P4PLAN_API_URL=http://host.docker.internal:4000",
        "perforce/p4plan-mcp:latest"
      ]
    }
  }
}

Note: Use host.docker.internal (macOS/Windows) or 172.17.0.1 (Linux) to reach the P4 Plan GraphQL API running on the host machine.

Pin a specific version by replacing :latest with :2026.3.2 (or whichever tag) for reproducible deployments.

Build locally (for development against unreleased changes):

docker build -t p4plan-mcp:dev .
# then swap "perforce/p4plan-mcp:latest" for "p4plan-mcp:dev" in the configs above

Configuration

Copy the example config and configure:

cp config-example.env .env

Edit .env with your settings:

# JWT token for authenticating with P4 Plan GraphQL API
# Obtain via: login mutation on the GraphQL API
P4PLAN_API_AUTH_TOKEN=your-jwt-token

# P4 Plan GraphQL API URL — base origin only. Do not include a path or a
# trailing slash: the server appends /graphql, /healthcheck and /attachment/<id>
# itself, so a trailing slash produces //graphql.
P4PLAN_API_URL=https://p4plan-api.example.com

# Logging
LOG_LEVEL=info

# Maximum number of results returned by search_tasks (default: 400)
# SEARCH_LIMIT=400

# Allow self-signed TLS certificates when connecting to the P4 Plan API over HTTPS
# Set to true if your API uses a self-signed or untrusted certificate
# P4PLAN_ALLOW_SELF_SIGNED_CERTS=true

# Read-only mode: expose only the tools that read (same as the --readonly argument)
# P4PLAN_READONLY=true

# Folders upload_attachment may read files from, besides the workspace folders
# the MCP client shares. Separate several with ":" (";" on Windows)
# P4PLAN_UPLOAD_DIRS=/Users/me/Screenshots:/Users/me/logs

The server communicates via stdin/stdout. It is not meant to be run interactively — MCP clients (VS Code, Claude Desktop) spawn it as a child process automatically.

Read-only mode

Start the server with the --readonly argument, or set P4PLAN_READONLY=true, to make it read-only:

• Only the tools that read are registered. Tools that create, update, comment, link, commit or delete are not offered to the model at all.

• As a second layer, every GraphQL request a tool makes is checked, and only plain queries are sent to the P4 Plan API. Mutations, subscriptions and anything that cannot be classified are refused.

• The model is told that changes are not available, so it explains this instead of trying. The skills that are only about writing (comment-html-format, mentions) are left out.

This means content read from P4 Plan (a task description or a comment, for example) cannot steer the model into changing data through this server.

{
    "servers": {
        "p4-plan": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "@perforce/p4plan-mcp", "--readonly"],
            "env": {
                "P4PLAN_API_AUTH_TOKEN": "YOUR_JWT_TOKEN",
                "P4PLAN_API_URL": "http://localhost:4000"
            }
        }
    }
}

With Docker, pass -e P4PLAN_READONLY=true or put --readonly after the image name. With Docker Compose, set P4PLAN_READONLY=true in your shell or .env; docker-compose.yml passes it to the container.

Read-only mode limits what the MCP server does; it does not change what the token may do. For the strongest guarantee, also authenticate as a P4 Plan user that only has read access.

Uploading files

upload_attachment attaches a local file, or text the model writes, to a task, bug, sprint or release. Reading local files would let a prompt injection ask for something like ~/.ssh/id_rsa, so the server only reads files inside allowed folders:

• the workspace folders your MCP client shares with the server (MCP roots), and

• the folders listed in P4PLAN_UPLOAD_DIRS (separate several with :, or ; on Windows).

Symlinks are resolved before the check, hidden files and folders (names starting with ., such as .env, .ssh or .git) are never uploaded, and only regular files are read. If the client shares no folders and P4PLAN_UPLOAD_DIRS is not set, only text uploads (content + fileName) work.

With Docker the container cannot see your files: mount a folder and point P4PLAN_UPLOAD_DIRS at the path inside the container, for example -v "$HOME/Screenshots:/uploads:ro" -e P4PLAN_UPLOAD_DIRS=/uploads, and pass paths such as /uploads/bug.png.

The file is streamed to the P4 Plan API (POST /attachment/<id>/upload), so its content never passes through the model. The P4 Plan server's own limits apply: its attachment size limit and blocked file types. If a file with the same name is already attached, the server stores the new one as name (1).ext. If an upload times out it may still have completed, so check get_attachments before retrying.

To show an image inside a comment or a multiline field (bug description, steps to reproduce, Multiline Text columns), upload it to the same item and put the returned imageHtml (<img src="hansoft://...">) in the HTML. This is how the P4 Plan clients embed pasted images; the server turns images with any other src into plain links.

So that one client cannot flood the P4 Plan API (a model stuck in a loop, or a prompt injection asking for many files), each MCP server runs its uploads one at a time and starts at most 20 uploads per minute. Further calls get an error saying how long to wait.

Every tool publishes MCP tool annotations. readOnlyHint marks the tools that only read; tools that write also carry destructiveHint (the call deletes or overwrites data) and idempotentHint. Clients that support annotations can use them to ask for confirmation before a write.

Authentication

The MCP server requires a JWT token provided via the P4PLAN_API_AUTH_TOKEN environment variable. The token is validated at startup and forwarded to the P4 Plan GraphQL API on every tool call. No sessions or state are maintained.

Obtaining a JWT Token

Get a JWT token from the P4 Plan GraphQL API using curl. You can authenticate with either your password or a Personal Access Token (PAT):

curl -s -X POST http://localhost:4000/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation Login($loginUserInput: LoginUserInput!) { login(loginUserInput: $loginUserInput) { access_token } }",
    "variables": { "loginUserInput": { "username": "YOUR_USERNAME", "password": "YOUR_PASSWORD" } }
  }'

A PAT can be used in place of your password in the same login mutation. This avoids exposing your actual password:

curl -s -X POST http://localhost:4000/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation Login($loginUserInput: LoginUserInput!) { login(loginUserInput: $loginUserInput) { access_token } }",
    "variables": { "loginUserInput": { "username": "YOUR_USERNAME", "password": "YOUR_PERSONAL_ACCESS_TOKEN" } }
  }'

Both methods return the same response:

{
  "data": {
    "login": {
      "access_token": "eyJhbGciOiJIUzI1NiIs..."
    }
  }
}

Copy the access_token value and use it in your MCP client configuration.

1. Log in to P4 Plan

2. Go to User Settings → Personal Access Tokens

3. Click Generate New Token

4. Set an appropriate expiration date

5. Copy the token — use it in the login mutation above to obtain a JWT

Note: JWT tokens expire. When your token expires, the server will fail to start with an authentication error. Generate a new JWT using the same curl command above.

Available Tools (31 total)

Tool arguments are parsed leniently, so less capable models succeed more often. Enum values match regardless of case, spaces, _ or - ("Time Spent" → timeSpent). "true"/"yes" are accepted for booleans, numbers for IDs, numeric strings for numbers, and JSON-encoded lists or comma-separated ID lists. Anything that can't be mapped unambiguously is rejected with the allowed values.

Projects

• Use cases: Discover project IDs needed by other tools

• Parameters: projectId

• Use cases: Retrieve section IDs (backlog, QA, planning) for other tools

• Parameters: name, optional methodTemplate, defaultMode, members (user or global group names/IDs), managers (normal user names/IDs), addMeAsManager (default true), or copyFromProjectId with copyUsers/copyColumns to base it on an existing project

• Use cases: Stand up a new project for a team without the UI. Requires P4 Plan administrator rights; steps that fail after the project is created are listed in failed

Tasks

• Parameters: showCompleted, showOnlyNextFourWeeks, showHidden, showPipelineTasksThatCannotStart

• Use cases: View personal work queue across all projects

• Parameters: taskIds (array of strings, max 20) -- database item IDs, i.e. the id returned by other tools

• Every item response includes both id (the database ID that all tools take) and localID (the number shown in the P4 Plan UI's "ID" column).

• Use cases: Full item details, link inspection, batch retrieval of multiple items

• Parameters: findQuery, projectId

• Uses P4 Plan Find query syntax for all searches. Call read_skill with skillName="search-queries" first to get exact column names, operators, and value formats. For simple name search use Itemname:Text("text"). Supports filtering by status, assignee, severity, item type, dates, boolean conditions, and combinations with AND/OR/NOT.

• Each project has three sections (Backlog, QA, Planning) with different IDs.

• To resolve an ID, query it directly: ID=<n> matches the UI "ID" column (the local ID, unique only within a section) and Databaseid=<n> matches the database ID.

• Use cases: Item discovery, filtering, reporting

• Types: backlog_task, bug, scheduled_task, sprint, release, sprint_task

• Parameters: type, name, projectId, parentItemId, previousItemId, and type-specific fields

• Use cases: Task creation, sprint creation, bug filing

• Types: BacklogTask, Bug, ScheduledTask, Sprint, Release

• Parameters: itemId, plus any updatable fields (name, status, assignedTo, points, etc.)

• Use cases: Status updates, assignments, estimation, sprint configuration

Sprint & Release Management

• Parameters: taskId, sprintId

• Use cases: Sprint planning, backlog commitment

• Parameters: taskId

• Use cases: Sprint scope adjustment

Custom Fields & Workflows

• Parameters: projectId

• Use cases: Discover custom fields before reading/writing values

• Parameters: projectId (planning, backlog or QA ID), name, columnType, activated, readOnly, plus type-specific unitName, updateOn*/updateOnlyFirstTime, useForTimeReporting/updateWorkRemaining, dropListItems (labels, or objects with icon, autoAssignToUsers, autoAssignToUserGroups)

• Use cases: Set up a project's columns without the UI. Requires main project manager rights

• Parameters: taskId, onlySet

• Use cases: Read project-specific metadata

• Parameters: taskId, customFieldId, value

• Use cases: Update project-specific metadata

• Parameters: projectId

• Use cases: Discover workflow statuses for status transitions

Task Actions

• Parameters: taskId

• Use cases: Quick status update convenience method

• Parameters: taskId

• Use cases: Quick status update convenience method

Comments & Attachments

• Parameters: taskId

• Use cases: Read discussion history

• Parameters: taskId, text

• Use cases: Add discussion, acceptance criteria, notes

• Parameters: taskId, commentId, text

• Use cases: Correct or update existing comments

• Parameters: taskId, commentId

• Use cases: Remove outdated or incorrect comments

• Parameters: taskId

• Use cases: List attached files, discover paths for download

• Parameters: taskId, path

• Text files returned inline, images as base64

• Use cases: Read attached documents, view screenshots

• Parameters: taskId, and either filePath (optionally fileName to rename it) or content + fileName

• Local files must be inside an allowed folder, see Uploading files

• Returns the new attachment path; the first image attached becomes the cover image

• For images it also returns imageHtml, an <img> tag that shows the image inside a comment, description, steps to reproduce or Multiline Text field of the same item

• Use cases: Attach screenshots, logs or repro files to bug reports and user stories

• Parameters: taskId, path

• Use cases: Remove outdated attachments

• Parameters: taskId, imagePath

• Use cases: Set visual identity for cards/items

Links

• Parameters: fromItemId, toItemId or url, relation (blocks, duplicates, relatedTo)

• Use cases: Dependency tracking, cross-references, external URLs

• Parameters: fromItemId, toItemId or url

• Use cases: Clean up outdated dependencies

Users

• Use cases: Identity verification, user context

• Parameters: projectId

• Use cases: Find user IDs for assignments, sprint member management

Skills

• Parameters: skillName

• Returns the full Markdown content of the requested skill document. The AI agent must call this with skillName="search-queries" before composing any findQuery for search_tasks.

• Available skills: project-navigation, search-queries, task-management, planning, backlog-refinement, bug-tracking, custom-fields, gantt-scheduling, workflows, pipeline, comment-html-format, mentions

• Use cases: Learn correct query syntax, discover tool usage patterns, understand domain concepts

Client Configuration

Create .vscode/mcp.json in your workspace:

{
    "servers": {
        "p4-plan": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "@perforce/p4plan-mcp"],
            "env": {
                "P4PLAN_API_AUTH_TOKEN": "YOUR_JWT_TOKEN",
                "P4PLAN_API_URL": "http://localhost:4000"
            }
        }
    }
}

Note: The -y flag auto-confirms the npm install prompt so the server starts without user interaction.

If running from a local clone instead of npm:

{
    "servers": {
        "p4-plan": {
            "type": "stdio",
            "command": "node",
            "args": ["/path/to/MCP/dist/main.js"],
            "env": {
                "P4PLAN_API_AUTH_TOKEN": "YOUR_JWT_TOKEN",
                "P4PLAN_API_URL": "http://localhost:4000"
            }
        }
    }
}

For added security, you can use VS Code input prompts to avoid storing tokens in files:

{
    "inputs": [
        {
            "type": "promptString",
            "id": "p4-plan-jwt",
            "description": "P4 Plan JWT Token",
            "password": true
        }
    ],
    "servers": {
        "p4-plan": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "@perforce/p4plan-mcp"],
            "env": {
                "P4PLAN_API_AUTH_TOKEN": "${input:p4-plan-jwt}",
                "P4PLAN_API_URL": "http://localhost:4000"
            }
        }
    }
}

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "p4-plan": {
      "command": "npx",
      "args": ["-y", "@perforce/p4plan-mcp"],
      "env": {
        "P4PLAN_API_AUTH_TOKEN": "YOUR_JWT_TOKEN",
        "P4PLAN_API_URL": "http://localhost:4000"
      }
    }
  }
}

Replace YOUR_JWT_TOKEN with a token obtained from the login mutation (see Obtaining a JWT Token).

Create .mcp.json in your project root:

{
  "mcpServers": {
    "p4-plan": {
      "command": "npx",
      "args": ["-y", "@perforce/p4plan-mcp"],
      "env": {
        "P4PLAN_API_AUTH_TOKEN": "YOUR_JWT_TOKEN",
        "P4PLAN_API_URL": "http://localhost:4000"
      }
    }
  }
}

For a local build, replace "command" and "args" with:

{
  "mcpServers": {
    "p4-plan": {
      "command": "node",
      "args": ["/path/to/MCP/dist/main.js"],
      "env": {
        "P4PLAN_API_AUTH_TOKEN": "YOUR_JWT_TOKEN",
        "P4PLAN_API_URL": "http://localhost:4000"
      }
    }
  }
}

Or add it via the CLI:

claude mcp add p4-plan \
  -e P4PLAN_API_AUTH_TOKEN=YOUR_JWT_TOKEN \
  -e P4PLAN_API_URL=http://localhost:4000 \
  -- npx -y @perforce/p4plan-mcp

Note: The server name must come before the -e flags, otherwise the variadic -e parser consumes the name as an env value.

Verify it's running: type /mcp inside Claude Code to check server status.

Tip: Place .mcp.json in your project root to share the config with your team (tokens excluded). For personal config, add the server to ~/.claude.json instead.

Verifying the Connection

1. Ensure the P4 Plan GraphQL API is running

2. Open VS Code with the workspace containing .vscode/mcp.json

3. Look for "MCP SERVERS" in the Extensions sidebar — you should see "p4-plan" listed

4. Start a new Copilot chat and ask "What tasks are assigned to me?"

Environment Variables

• P4PLAN_API_AUTH_TOKEN - JWT token for authenticating with the P4 Plan GraphQL API

• P4PLAN_API_URL - P4 Plan GraphQL API URL, base origin only — no path, no trailing slash (the server appends /graphql, /healthcheck and /attachment/<id>). Defaults to http://localhost:4000 when unset; config-example.env ships an HTTPS example.

• P4PLAN_ALLOW_SELF_SIGNED_CERTS - Set to true to accept self-signed or untrusted TLS certificates when connecting to the API over HTTPS (default: false)

• P4PLAN_READONLY - Set to true (or 1, yes, on) to expose only the tools that read, same as the --readonly argument (default: false). Case and surrounding spaces are ignored; an unrecognised value turns read-only mode on and logs a warning. See Read-only mode

• P4PLAN_UPLOAD_DIRS - Folders upload_attachment may read files from, in addition to the workspace folders the MCP client shares. Separate several with : (; on Windows). See Uploading files

• LOG_LEVEL - Logging level: debug, info, warn, error (default: debug)

• SEARCH_LIMIT - Maximum number of results returned by search_tasks (default: 400)

Skills & Resources

The server includes skill files — domain-specific guides that help AI agents construct correct tool calls. Skills are accessible in two ways:

• read_skill tool — any MCP client can call read_skill with a skillName to fetch skill content at runtime. This is the primary access method and works with all clients.

• MCP resources — skills are also registered as MCP resources (e.g., skill://p4-plan/search-queries) for clients that support native resource reading.

See skills/README.md for details on using skills with different AI clients.

Development

To test the npx experience locally without publishing to npm:

# Build and create a global symlink
npm run build
npm link

# Now test exactly as an end user would
P4PLAN_API_AUTH_TOKEN=your-jwt-token npx @perforce/p4plan-mcp

# Clean up when done
npm unlink -g @perforce/p4plan-mcp

The symlink persists across rebuilds — just run npm run build after code changes.

1. Create or edit a tools file in src/tools/

2. Define the tool with:

   • name: Unique tool identifier

   • description: What the tool does (shown to AI)

   • inputSchema: JSON Schema for parameters

   • handler: Function that executes the tool

3. Register in ToolsModule

# Unit tests
npm run test

# E2E tests (MCP protocol compliance via @modelcontextprotocol/sdk)
npm run test:e2e

Logging

The server uses Winston with two transports:

• Console (stderr): Only warnings and errors are written to stderr. In VS Code, these appear in the Output panel under the "p4-plan" dropdown. Only warn and error level messages are shown to keep the output clean.

• File: Full debug logs are written to logs/P4PlanMCP_<timestamp>.log. Use these for detailed troubleshooting.

Note: All console output goes to stderr (never stdout) because stdout is the MCP protocol channel. VS Code labels all stderr output as [warning] — this is expected behavior and does not indicate a problem.

Protocol

This server uses the MCP stdio transport — communication happens over stdin/stdout using JSON-RPC 2.0 messages. The client spawns the server as a child process.

• Transport: stdio (stdin/stdout)

• Protocol: JSON-RPC 2.0

• Authentication: P4PLAN_API_AUTH_TOKEN environment variable (validated at startup)

• SDK: @modelcontextprotocol/sdk with StdioServerTransport

Troubleshooting

1. Check P4PLAN_API_AUTH_TOKEN is set: The server requires a valid JWT token in the P4PLAN_API_AUTH_TOKEN environment variable. If missing, it exits immediately with an error.

2. Check token is valid: If the token is expired or invalid, the server exits with "Authentication failed". Generate a new JWT using the login mutation.

3. Check GraphQL API is reachable: The P4 Plan GraphQL API must be accessible at the configured P4PLAN_API_URL (default: http://localhost:4000).

1. Verify mcp.json syntax: Ensure your .vscode/mcp.json is valid JSON. Check for trailing commas.

2. Check the command is available: If using npx, ensure Node.js is in VS Code's PATH. If npx is not found, use the absolute path to node instead (see local build config).

3. Reload VS Code window: Press Cmd+Shift+P → "Developer: Reload Window"

4. Start a new chat: MCP servers are connected when a new chat session starts.

1. Check GraphQL server is running: The P4 Plan GraphQL API must be accessible at the configured URL.

2. Check server logs: In VS Code, check the Output panel → select "p4-plan" from the dropdown to see warnings/errors. For full debug logs, check the logs/ directory.

3. Verify the JWT hasn't expired: Generate a new JWT if needed and update your mcp.json config.

License

This project is licensed under the MIT License. See LICENSE for details.