MCP server

Expose your PulseLight launch verdict, top blockers, and paste-ready fix prompts to any MCP-aware editor — Cursor, Claude Code, and friends — without leaving the editor.

Early access. @pulselight/mcp is preparing for npm publish; the install commands below assume the package is live. Track the publish ship date on /changelog.

What it is

The PulseLight MCP server is a stdio Model Context Protocol server that hands three tools to whichever AI editor you wire it into:

  • pulse_status — verdict, blocker counts, per-pillar status, and the Top 3 fixes for the project.
  • pulse_top_blockers — full Fix Queue rows with founder copy, file location, and why-it-matters body.
  • pulse_fix_prompt — the v2 restraint-engineered fix prompt for a chosen finding, ready to paste into the editor.

Same three tools across every host. Same data model the dashboard renders. The MCP is read-only — it never mutates your repo or your PulseLight workspace.

Install

01

Install the MCP server globally.

npm install -g @pulselight/mcp
02

Mint a Personal Access Token in the dashboard: Settings → API tokens → Create token. Copy the pul_… string — it’s shown exactly once.

03

Find your workspace ID in the dashboard URL after you log in (app.pulselight.io/dashboard?wid=ws_…) or on the same Settings → API tokens page.

Configure for Cursor

Cursor reads MCP servers from ~/.cursor/mcp.json (global) or .cursor/mcp.json at your repo root (project-scoped). Add:

{
  "mcpServers": {
    "pulselight": {
      "command": "pulselight-mcp",
      "env": {
        "PULSELIGHT_TOKEN": "pul_…",
        "PULSELIGHT_WORKSPACE_ID": "ws_…"
      }
    }
  }
}

Restart Cursor. Open a chat and try:

Use pulse_status to tell me what's blocking this branch from shipping.

Configure for Claude Code

Claude Code reads project-scoped servers from .mcp.json at the repo root, or global servers from ~/.claude/mcp_servers.json. Same shape:

{
  "mcpServers": {
    "pulselight": {
      "command": "pulselight-mcp",
      "env": {
        "PULSELIGHT_TOKEN": "pul_…",
        "PULSELIGHT_WORKSPACE_ID": "ws_…"
      }
    }
  }
}

Restart Claude Code. Ask:

Is this branch safe to ship?

Claude Code will see pulse_status and friends in its tool list and call them when the conversation warrants — no per-tool prompt engineering required.

Authentication

Auth is one Bearer token per env. The MCP server reads PULSELIGHT_TOKEN and PULSELIGHT_WORKSPACE_ID from its environment and sends them to the API on every call. The token never enters your repo, your editor config, or any third-party cache — just the editor’s MCP config file on your machine.

Tokens act as you. Your existing workspace memberships gate which projects each token can read. Revoke any token from Settings → API tokens — once revoked, the next call from that token returns a 401, and any client using it loses access immediately.

Treat tokens like passwords. If you suspect one has leaked, revoke it first and mint a replacement second. The dashboard list shows last-used timestamps so you can spot a token that’s active when you didn’t expect it to be.

Troubleshooting

The editor doesn’t see the tools. Check that the MCP server is actually launching: run pulselight-mcp directly in your terminal — it should sit waiting on stdin. Restart your editor after every config edit.

Calls return 401. Either the token is wrong, expired, or revoked. Check Settings → API tokens — if the row is missing, mint a new one.

Calls return “No PulseLight project for <repo>”. The repo isn’t connected as a PulseLight project yet. Install the GitHub App and add the repo from the dashboard, then retry.

Rate-limited (429). Per-token rate limits are 60 requests / minute on most endpoints, 10 requests / minute on pulse_fix_prompt (the expensive renderer). If you’re hitting these from a legitimate workflow, mint a second token for the second client — each token gets its own bucket.

What’s next

See /works-with-cursor and /works-with-claude-code for the editor-specific positioning. For CI gating, the same data plane ships as a GitHub Action; that page lands when @pulselight/scan-action publishes.