Pinpoint MCP Server

MCP server for the Pinpoint testing and bug tracking platform. Enables AI agents in Claude Code, Cursor, and other MCP-compatible environments to manage projects, environments, test requests, bug reports, Spectre scan findings, and dependency insights directly from the editor.

Quick Start

Install from npm

npx -y pinpointmcp@latest

That's it. The server starts without any pre-configuration and exposes a configure tool so your AI agent can set up credentials interactively. You can also pre-configure via environment variables or a dotfile (see Configuration below).

Configuration

The server resolves credentials in this order:

1. Environment variables (highest precedence)
2. Dotfile at ~/.pinpoint/config.json
3. Unconfigured (server starts, all tools return setup guidance until configured)

Option 1: Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | PINPOINT_TOKEN | No | n/a | API authentication token | | PINPOINT_API_URL | No | https://api.testwithpinpoint.com | API base URL |

export PINPOINT_TOKEN=your-token-here

Option 2: Interactive Configuration (First-Boot)

Launch the server without any token set. The agent can then call the configure tool:

{ "token": "your-pinpoint-api-token" }

The server validates the token against the API, swaps in a live client, and persists the credentials to ~/.pinpoint/config.json (with 0600 file permissions) for future sessions.

Option 3: Dotfile

Create ~/.pinpoint/config.json manually:

{
  "token": "your-pinpoint-api-token",
  "apiUrl": "https://api.testwithpinpoint.com"
}

Claude Code / Cursor / Windsurf

Add to your project's .mcp.json (or the equivalent for your platform):

{
  "mcpServers": {
    "pinpoint": {
      "command": "npx",
      "args": ["-y", "pinpointmcp"]
    }
  }
}

If you have a token ready, you can pass it as an environment variable to skip the interactive setup:

{
  "mcpServers": {
    "pinpoint": {
      "command": "npx",
      "args": ["-y", "pinpointmcp"],
      "env": {
        "PINPOINT_TOKEN": "your-token-here"
      }
    }
  }
}

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "pinpoint": {
      "command": "npx",
      "args": ["-y", "pinpointmcp"]
    }
  }
}

Tech Stack

• Runtime: Node.js >= 18
• Language: TypeScript 5.9+
• MCP SDK: @modelcontextprotocol/sdk 1.27+
• Validation: Zod 4.3+
• Testing: Vitest 4.0+
• Build: TypeScript compiler (tsc)

Project Structure

src/
├── index.ts                 # Main server entry point
├── client.ts                # Pinpoint API client
├── client-holder.ts         # Client lifecycle management
├── config.ts                # Configuration loading
├── config-store.ts          # Persistent config storage
├── setup-message.ts         # Unconfigured-state helpers (used by every tool/resource/prompt)
├── types.ts                 # Shared TypeScript types
├── __tests__/               # Vitest test suite (18 files)
│   ├── analysis-resources.test.ts
│   ├── analysis-tools.test.ts
│   ├── client.test.ts
│   ├── client-holder.test.ts
│   ├── config.test.ts
│   ├── config-store.test.ts
│   ├── configure-tool.test.ts
│   ├── environment-tools.test.ts
│   ├── graph-query-tools.test.ts
│   ├── integration.test.ts
│   ├── project-tools.test.ts
│   ├── prompts.test.ts
│   ├── report-tools.test.ts
│   ├── request-tools.test.ts
│   ├── resources.test.ts
│   ├── setup-message.test.ts
│   ├── tools.test.ts
│   └── update-tools.test.ts
├── tools/                   # MCP tool implementations (25 tools)
│   ├── index.ts             # Barrel export
│   ├── configure.ts         # Runtime configuration
│   ├── list-bugs.ts         # Bug listing
│   ├── get-bug.ts           # Bug details
│   ├── update-bug-status.ts # Bug status updates
│   ├── list-projects.ts     # Project listing
│   ├── create-project.ts    # Project creation
│   ├── update-project.ts    # Project updates
│   ├── delete-project.ts    # Project deletion
│   ├── list-environments.ts # Environment listing
│   ├── add-environment.ts   # Environment creation
│   ├── update-environment.ts# Environment updates
│   ├── remove-environment.ts# Environment deletion
│   ├── list-requests.ts     # Test request listing
│   ├── create-request.ts    # Test request creation
│   ├── get-request.ts       # Test request details
│   ├── get-report.ts        # Report details
│   ├── download-report.ts   # Report download URLs
│   ├── list-dispatch-reports.ts # Reports for a dispatch
│   ├── list-analysis-findings.ts # Spectre scan findings
│   ├── list-analysis-runs.ts    # Spectre scan runs
│   ├── get-analysis-finding.ts  # Scan finding details
│   ├── update-finding-status.ts # Finding status updates
│   └── graph-query.ts       # Blast radius, dependency chain, test coverage
├── resources/               # MCP resource implementations
│   ├── index.ts             # Barrel export
│   ├── bugs.ts              # Bug resources
│   ├── projects.ts          # Project resources
│   ├── requests.ts          # Request resources
│   └── analysis.ts          # Scan and finding resources
└── prompts/                 # MCP prompt templates
    ├── index.ts             # Barrel export
    ├── solve-bug.ts         # Bug solving workflow
    ├── review-request.ts    # Test request review
    └── fix-finding.ts       # Scan finding fix workflow

Build and Run

# Install dependencies
npm install

# Build TypeScript to JavaScript
npm run build

# Run the server (after building)
npm start

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Development mode (watch for changes)
npm run dev

Tools

configure

Configure the server with an API token at runtime. Validates the token before persisting.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | token | string | Yes | n/a | Your Pinpoint API token | | api_url | string | No | https://api.testwithpinpoint.com | API base URL for self-hosted instances |

Behavior:

• Validates the token by making a lightweight API call
• On success: swaps the live client, persists to ~/.pinpoint/config.json, returns confirmation
• On validation failure: returns an error without persisting
• On write failure: configures the current session and warns about persistence

Bug Management

list_bugs

List bug reports filtered by status and project.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | status | string | No | all non-verified | Filter: open, in_progress, in_review, needs_rework, complete, verified. Omit to see all active bugs. Supports comma-separated values (e.g., "open,in_progress,needs_rework") | | project | string | No | n/a | Filter by project name | | cursor | string | No | n/a | Cursor token from a previous response for efficient pagination through large lists | | page | number | No | 0 | Page number (0-indexed). Ignored when cursor is provided | | size | number | No | 20 | Page size (max 200) |

get_bug

Get detailed information about a specific bug report, including description, reproduction steps, expected/actual behavior, and environment.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | Bug report UUID |

update_bug_status

Update the status of a bug report.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | Bug report UUID | | status | enum | Yes | New status: open, in_progress, complete (only Pinpoint staff can set in_review, needs_rework, or verified) | | resolution | string | No | Resolution notes (recommended when marking complete) |

Bug Status Lifecycle

Pinpoint uses a multi-gate verification model to ensure bugs are truly fixed before they leave your board. Each bug progresses through six statuses:

OPEN ──► IN_PROGRESS ──► COMPLETE ──► IN_REVIEW ──► VERIFIED
                             │            │
                             │      NEEDS_REWORK
                             │            │
                             └── OPEN ◄───┘

| Status | Who sets it | Meaning | |--------|-------------|---------| | open | Pinpoint | Bug discovered during testing. Needs attention. | | in_progress | Customer | Your team is actively working on a fix. | | complete | Customer | Your team believes the fix is deployed. First quality gate. | | in_review | Pinpoint staff only | Pinpoint is actively verifying the fix in your environment. | | needs_rework | Pinpoint staff only | Pinpoint found the bug still reproduces. Returned for additional work. | | verified | Pinpoint staff only | Pinpoint verified the fix works in your environment. Final quality gate. |

Only Pinpoint staff can set in_review, needs_rework, or verified. If staff find the bug still reproduces after you mark it complete, they set needs_rework so your team can investigate further.

Bug Workflow

List all active bugs

Call list_bugs with no status parameter to see every bug that is not verified. This returns all OPEN, IN_PROGRESS, IN_REVIEW, NEEDS_REWORK, and COMPLETE bugs in a single request.

{ "project": "my-app" }

Filter by project

Narrow results to bugs in a specific codebase so you can focus on what you are actively changing.

{ "project": "checkout-service" }

Triage with multi-status filtering

Use comma-separated status values to see only bugs that still need attention. Filtering to "open,in_progress" excludes bugs your team already marked complete.

{ "status": "open,in_progress", "project": "checkout-service" }

Fix a bug end-to-end

1. Find open bugs for your project:

   list_bugs { "status": "open", "project": "checkout-service" }

2. Read the details including reproduction steps and expected behavior:

   get_bug { "id": "bug-uuid-here" }

3. Claim the bug so your team knows someone is on it:

   update_bug_status { "id": "bug-uuid-here", "status": "in_progress" }

4. Fix and deploy the code in your editor or through your AI agent.

5. Mark complete with a note describing what changed:

   update_bug_status { "id": "bug-uuid-here", "status": "complete", "resolution": "Fixed null check in payment validation; added unit test" }

6. Pinpoint verifies the fix during the next test cycle and marks the bug as verified if it passes. If the bug still reproduces, Pinpoint reopens it with updated details.

Paginate large bug lists

For projects with many bugs, use cursor-based pagination. The response includes hasMore and nextCursor fields when additional pages exist.

First request:

list_bugs { "project": "large-project", "size": 50 }

If the response contains "hasMore": true and a "nextCursor" value, pass that cursor to fetch the next page:

list_bugs { "project": "large-project", "size": 50, "cursor": "returned-cursor-token" }

Continue until hasMore is false. When a cursor is provided, the page parameter is ignored.

Project Management

list_projects

List all projects for your organization.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | page | number | No | 0 | Page number (0-indexed) | | size | number | No | 20 | Page size (max 200) |

create_project

Create a new project in your organization.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | name | string | Yes | Project name | | description | string | No | Project description | | type | string | No | Project type (UI, API, CLI, MCP) |

update_project

Update a project's name, description, or type.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | projectId | string | Yes | Project UUID | | name | string | No | New project name | | description | string | No | New project description | | type | string | No | New project type |

delete_project

Delete a project by ID.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | Project UUID |

Environment Management

list_environments

List environments for a project.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | projectId | string | Yes | Project UUID |

add_environment

Add a new environment to a project.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | projectId | string | Yes | Project UUID | | name | string | Yes | Environment name (e.g., staging, production) | | baseUrl | string | Yes | Base URL for the environment | | isDefault | boolean | No | Whether this is the default environment |

update_environment

Update an environment's configuration.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | projectId | string | Yes | Project UUID | | environmentId | string | Yes | Environment UUID to update | | name | string | No | New environment name | | baseUrl | string | No | New base URL | | isDefault | boolean | No | Set as the default environment |

remove_environment

Remove an environment from a project.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | projectId | string | Yes | Project UUID | | environmentId | string | Yes | Environment UUID to remove |

Test Request Management

list_requests

List test requests for your account.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | page | number | No | 0 | Page number (0-indexed) | | size | number | No | 20 | Page size (max 200) |

create_request

Create a new manual test request (dispatch).

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | projectId | string | Yes | Project UUID to dispatch tests for | | environment | string | Yes | Target environment name (e.g., staging, production) | | buildUrl | string | No | CI/CD build URL | | commitSha | string | No | Git commit SHA | | branch | string | No | Git branch name | | triggeredBy | string | No | Who triggered this request |

get_request

Get detailed information about a specific dispatch.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | Dispatch UUID |

Report Management

get_report

Get detailed information about a specific report.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | Report UUID |

download_report

Get a presigned download URL for a report attachment.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | Report UUID |

Note: Presigned URLs expire in 1 hour.

list_dispatch_reports

List all reports for a specific dispatch event.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | dispatch_id | string | Yes | Dispatch event UUID |

Spectre Scan

Spectre is Pinpoint's static analysis engine. These tools let your agent browse scan results and triage findings without leaving the editor.

list_scan_runs

List Spectre scan runs for a project, showing commit, branch, and finding counts.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | projectId | string | Yes | Project UUID |

list_scan_findings

List Spectre scan findings for a project, filtered by category, severity, or status.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | projectId | string | Yes | n/a | Project UUID | | category | string | No | n/a | Filter by finding category (e.g., CONTRACT_MISMATCH, DEAD_CODE, MISSING_VALIDATION) | | severity | string | No | n/a | Filter by severity: LOW, MEDIUM, HIGH, CRITICAL | | status | string | No | n/a | Filter by status: OPEN, ACKNOWLEDGED, RESOLVED, FALSE_POSITIVE | | page | number | No | 0 | Page number (0-indexed) | | size | number | No | 20 | Page size (max 200) |

get_scan_finding

Get detailed information about a specific Spectre scan finding, including source location, description, suggested fix, and related components.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | findingId | string | Yes | Scan finding UUID |

update_finding_status

Update the status of a scan finding.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | findingId | string | Yes | Scan finding UUID | | status | enum | Yes | New status: ACKNOWLEDGED, RESOLVED, or FALSE_POSITIVE |

Dependency Insights

Query the project dependency graph built by Spectre scans. Useful for understanding change impact and identifying untested components.

get_blast_radius

Compute the blast radius for a component in a project's dependency graph. Returns the proportion of the graph reachable within the specified hop distance, along with the names of affected components.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | projectId | string | Yes | n/a | Project UUID | | vertexName | string | Yes | n/a | Name of the component to compute blast radius from | | maxHops | number | No | 3 | Maximum BFS traversal depth (1 to 10) |

get_dependency_chain

Traverse the dependency chain from a component in a project's graph. Returns the chain of dependencies with relationship labels, limited by the specified depth.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | projectId | string | Yes | n/a | Project UUID | | vertexName | string | Yes | n/a | Name of the component to start traversal from | | maxDepth | number | No | 5 | Maximum DFS traversal depth (1 to 20) |

get_test_coverage

Calculate test coverage for a scope in a project's graph by examining tested-by edge ratios. Returns the percentage of components that have associated tests.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | projectId | string | Yes | Project UUID | | scope | string | Yes | Scope prefix to filter components (e.g., AuthService, com.example.auth) |

Resources

Resources provide read-only access to Pinpoint data via URIs.

| URI | Format | Description | |-----|--------|-------------| | pinpoint://bugs | JSON | All non-verified bugs as a JSON array (OPEN, IN_PROGRESS, IN_REVIEW, NEEDS_REWORK, COMPLETE) | | pinpoint://bugs/{id} | Markdown | Detailed bug report rendered as Markdown | | pinpoint://projects | JSON | All projects as a JSON array | | pinpoint://projects/{id} | Markdown | Detailed project information rendered as Markdown | | pinpoint://projects/{id}/scans | JSON | Summary of latest scan run and finding counts by severity | | pinpoint://requests/{id} | Markdown | Detailed test request information rendered as Markdown | | pinpoint://findings/{id} | Markdown | Detailed scan finding with location, description, and related components |

Prompts

Prompts provide structured workflows for common tasks.

solve_bug

Structured prompt for analyzing and fixing a specific bug. Assembles the title, description, reproduction steps, expected/actual behavior, and environment into a context block, then asks the agent to identify the root cause, implement a fix, and create a merge request.

| Argument | Type | Required | Description | |----------|------|----------|-------------| | bug_id | string | Yes | UUID of the bug to solve |

review_request

Analyze test request results and associated reports. Gathers all reports for a dispatch event and asks the agent to identify patterns across bugs and suggest improvements.

| Argument | Type | Required | Description | |----------|------|----------|-------------| | request_id | string | Yes | UUID of the test request to review |

fix_finding

Structured prompt for fixing a specific Spectre scan finding in your codebase. Assembles the finding's location, description, severity, suggested action, related components, and blast radius into a context block, then asks the agent to implement the fix and verify with tests.

| Argument | Type | Required | Description | |----------|------|----------|-------------| | finding_id | string | Yes | UUID of the scan finding to fix |

Prerequisites

• Node.js: Version 18 or higher
• Pinpoint Account: Sign up at testwithpinpoint.com
• API Token: Generate from the Pinpoint dashboard (Settings > API Tokens)

Troubleshooting

• Server starts but tools return setup guidance: No token is configured. Either set PINPOINT_TOKEN, create the dotfile, or ask the agent to call the configure tool.
• "Token validation failed": The token was rejected by the API. Verify it is valid and has not expired. Check the Pinpoint dashboard under Settings > API Tokens.
• "Could not save configuration to disk": The server configured successfully for this session but could not write ~/.pinpoint/config.json. Check directory permissions on ~/.pinpoint/.
• "Authentication failed" on tool calls: Your stored or environment token may have expired. Re-run the configure tool with a fresh token.
• Connection errors: Check PINPOINT_API_URL and confirm network connectivity to the API.
• Server not discovered by Claude Code: Ensure .mcp.json exists in the project root and that npm run build has been executed so dist/index.js is present.
• TypeScript compilation errors: Ensure you have TypeScript 5.9+ installed and run npm install to install dependencies.
• Test failures: Run npm test to execute the test suite. Ensure all dependencies are installed and the build is up to date.