P4plan MCP README

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.

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

npm ci
npm run build

# For using npx locally
npm link

{
    "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"
            ]
        }
    }
}

{
  "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"
      ]
    }
  }
}

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="https://raw.githubusercontent.com/perforce/p4plan-mcp/HEAD/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" } }
  }'

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.

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

Tasks

Sprint & Release Management

Custom Fields & Workflows

Task Actions

Comments & Attachments

Links

Users

Skills

Client Configuration

{
    "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"
            }
        }
    }
}

{
    "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"
            }
        }
    }
}

{
    "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"
            }
        }
    }
}

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

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

{
  "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"
      }
    }
  }
}

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

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

# 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

# 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

License

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