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

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

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

• Use cases: Discover project IDs needed by other tools

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

• Parameters: showCompleted, showOnlyNextFourWeeks, showHidden, showPipelineTasksThatCannotStart
• Use cases: View personal work queue across all projects

• Parameters: taskIds (array of strings, max 20)
• 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.
• 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

• Parameters: taskId, sprintId
• Use cases: Sprint planning, backlog commitment

• Parameters: taskId
• Use cases: Sprint scope adjustment

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

• Parameters: taskId, onlySet
• Use cases: Read project-specific metadata

• Parameters: taskId, columnId, value
• Use cases: Update project-specific metadata

• Parameters: projectId
• Use cases: Discover workflow statuses for status transitions

• Parameters: taskId
• Use cases: Quick status update convenience method

• Parameters: taskId
• Use cases: Quick status update convenience method

• 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, path
• Use cases: Remove outdated attachments

• Parameters: taskId, imagePath
• Use cases: Set visual identity for cards/items

• 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

• Use cases: Identity verification, user context

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

• 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
• Use cases: Learn correct query syntax, discover tool usage patterns, understand domain concepts

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.

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

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.