Buildpulse MCP README

Model Context Protocol server for the BuildPulse Platform API. Surface flaky tests, CI run history, and coverage health in Claude Desktop, Cursor, ChatGPT, Cline, Windsurf, Continue, Zed, VS Code Copilot, and any other MCP-aware AI agent.

Quickstart

Hosted (recommended) — nothing to install, no API token. Your client opens a browser and you sign in with your BuildPulse account (Google, GitHub, Bitbucket, Apple, or email):

claude mcp add --transport http buildpulse https://mcp.buildpulse.io/mcp

Claude.ai, ChatGPT, Cursor, VS Code: add https://mcp.buildpulse.io/mcp as an HTTP/remote MCP server and complete the sign-in when prompted.

Local stdio — for clients that only spawn a process, or for scripts and CI where a browser sign-in is not possible. This path needs an API token:

BUILDPULSE_TOKEN=bp_... npx -y @buildpulse/mcp

See Authentication for where tokens come from and when you need one.

Try asking

• "Why is CI red on web-client? Show me the failing tests from the last run."
• "Which tests in platform-api have been flakiest this week, and where do they fail?"
• "How well tested is agents? Give me flakiness and coverage."
• "Which tests failed in more than one of the last 10 runs of api?"
• "Triage the flaky tests in frontend and tell me which to quarantine first."

Install

npx -y @buildpulse/mcp

Or pin globally:

npm install -g @buildpulse/mcp

The package downloads the matching native binary for your platform on first install. Supported platforms: macOS arm64/x64, Linux arm64/x64, Windows x64.

Authentication

There are two ways to authenticate, and most people only need the first.

Get a token at https://buildpulse.io → Organization Settings → API Tokens. Tokens look like bp_<64 hex chars>; the older 40-character hex tokens still work. A token grants access to the same organizations your account does.

Configure

Hosted snippets sign you in via SSO. Stdio snippets need BUILDPULSE_TOKEN; replace bp_... with your token.

Claude Code

Hosted (SSO, no token):

claude mcp add --transport http buildpulse https://mcp.buildpulse.io/mcp

Stdio (token):

claude mcp add buildpulse -e BUILDPULSE_TOKEN=bp_... -- npx -y @buildpulse/mcp

Claude Desktop

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

{
  "mcpServers": {
    "buildpulse": {
      "command": "npx",
      "args": ["-y", "@buildpulse/mcp"],
      "env": { "BUILDPULSE_TOKEN": "bp_..." }
    }
  }
}

Cursor

.cursor/mcp.json (per-project) or ~/.cursor/mcp.json (global). Hosted with SSO (Cursor prompts you to sign in the first time):

{
  "mcpServers": {
    "buildpulse": {
      "url": "https://mcp.buildpulse.io/mcp"
    }
  }
}

To use a token instead of signing in, add "headers": { "Authorization": "Bearer bp_..." }. For stdio, use the command / args / env shape from the Claude Desktop snippet.

VS Code (GitHub Copilot agent mode)

.vscode/mcp.json. Hosted with SSO (VS Code opens the sign-in when the server first starts):

{
  "servers": {
    "buildpulse": {
      "type": "http",
      "url": "https://mcp.buildpulse.io/mcp"
    }
  }
}

To use a token instead, add "headers": { "Authorization": "Bearer bp_..." }. For stdio, use "type": "stdio" with the command / args / env fields from the Claude Desktop snippet.

Windsurf

~/.codeium/windsurf/mcp_config.json — same mcpServers block as Claude Desktop.

Cline

Cline → MCP Servers → Configure → paste the same mcpServers block into cline_mcp_settings.json.

ChatGPT

ChatGPT → Settings → Connectors → Create → URL https://mcp.buildpulse.io/mcp. ChatGPT completes the SSO sign-in; no token to paste.

Claude.ai

Settings → Connectors → Add custom connector → URL https://mcp.buildpulse.io/mcp. Sign in when prompted; no token.

Other clients

Continue, Zed, and anything else MCP-aware takes the same command / args / env fields. See the install hub for copy-paste snippets per client.

Organizations (multi-tenant)

Your BuildPulse token may grant access to more than one organization. Every repo-scoped tool takes an optional organization_id argument (the org's id UUID, discoverable via list_my_organizations):

• Single-org tokens — omit organization_id. It auto-defaults to your one organization. Nothing changes; you never need to think about orgs.
• Multi-org sessions (list_my_organizations returns 2+ orgs) — you must pass organization_id on every repo-scoped call (list_repositories, find_flaky_tests, get_test_history, list_recent_submissions, get_submission_test_results, get_recent_failures, get_repo_flakiness, get_repo_coverage). The org is not auto-selected — omitting it returns an error that lists every accessible organization and its UUID, so the agent can pick the right one and retry. Call list_my_organizations first to enumerate them.

This avoids silently querying the wrong (often empty) organization and getting confusingly empty results.

Tools

Repo-scoped tools accept an organization_id argument — required for multi-org sessions, optional (auto-defaulted) for single-org tokens. See Organizations above.

Every output that names a test or repo includes a web_url deep-link back to the BuildPulse web app — the same polish Sentry / Atlassian use in their MCP responses.

Prompts

The server also ships four guided prompts (slash-pickable in clients that support them):

• /triage_flaky_tests
• /ci_health_check
• /explain_test_failure
• /whats_red

Two transports

Same tool surface; same prompts; same resources. Pick whichever your client supports. The stdio path is universal; the hosted variant is the path to Claude.ai web and ChatGPT, and authenticates with OAuth 2.1 SSO by default (PKCE + dynamic client registration; discovery at /.well-known/oauth-authorization-server) or a Bearer API token. The hosted server also publishes a landing page, robots.txt, sitemap.xml, and llms.txt on the bare host.

Resources

The server exposes two MCP resource templates so agents can pull state into context without a tool call:

• buildpulse://repos/{repo}/flaky-tests
• buildpulse://repos/{owner}/{name}/submissions

Environment variables

The hosted server (mcp-remote) will refuse to start unless PLATFORM_API_URL is production or development Platform API. Local stdio (npx @buildpulse/mcp) is unchanged. See SECURITY.md for the threat model, tenant isolation, P1 rate limits (120 tool calls / token / minute), the tool audit log, RFC 7009 /oauth/revoke, and what we deliberately do not gate (HITL on reads, hiding tools, killing multi-step triage).

Build from source

git clone https://github.com/BuildPulseLLC/buildpulse-mcp
cd buildpulse-mcp
go build -o ./bin/buildpulse-mcp ./cmd/mcp
go build -o ./bin/buildpulse-mcp-remote ./cmd/mcp-remote

Requires Go 1.26+ (see go.mod).

Run tests

go test -race ./...

See CONTRIBUTING.md for the development workflow and CHANGELOG.md for release history.

License

MIT — see LICENSE.

Related

• BuildPulse Platform API — the underlying public REST API
• @buildpulse/mcp on npm
• Distribution strategy — Claude, OpenAI, Smithery, Cursor publishing details
• /docs/mcp — branded install hub with copy buttons
• MCP Registry listing — io.github.BuildPulseLLC/buildpulse-mcp