MCP server (for coding agents)

What this is#

MCP (Model Context Protocol) is how a coding agent — Claude Code, Claude Desktop, or any other MCP client — gets tools it can call. Harpoon ships an MCP server, so the agent working on your code can measure the page it is editing instead of guessing at performance from source.

Ask it "did that change make the page slower?" and it captures a real page load, runs the deterministic engine, and reads back a score with a ranked list of what is costing you. The findings come from measurement, not from the model's judgement — which is precisely what makes them worth handing to a model.

It runs on your machine — including localhost#

The engine runs in the server process, locally. That is not a detail: an agent editing http://localhost:5173 needs a browser that can actually reach localhost, and a hosted analyzer never can. It also means the core tools need no account, no API token, and no network call — the same "analysis is free and needs no signup" promise the web app makes.

Add an API token later if you want runs kept in your workspace history; see the cloud tools below.

Setting it up#

The server speaks stdio, so a client just spawns it. Capturing a live URL needs a Chromium — install one once:

npx playwright-core install --with-deps chromium

Claude Code — add it from the command line, or put the same block in your MCP config:

claude mcp add harpoon -- npx -y harpoon-mcp

Claude Desktop and other MCP clients — add a server entry to the client's config file:

{
  "mcpServers": {
    "harpoon": {
      "command": "npx",
      "args": ["-y", "harpoon-mcp"],
      "env": {
        "HARPOON_API_TOKEN": "hpn_..."
      }
    }
  }
}

The tools#

Local — always available, no account:

With an API token — your workspace:

Mint the token under Settings → CI & API tokens. It is the same token the HTTP API uses and carries the same deliberate limits: it acts as your workspace with member-level rights, and it cannot manage billing, workspace membership, or other tokens. An agent with this server cannot spend your money.

What comes back#

• Markdown, not JSON. Results are the same report the app renders, so the agent reads prose and a findings table rather than re-serializing a blob.
• Bounded. Output is capped so one call cannot swallow the context window. Findings are ordered worst-first, so what survives a cut is what matters; the result says so explicitly when it was truncated. Raise HARPOON_MCP_MAX_CHARS if you want the whole thing.
• Never your raw capture. The server returns engine output — the curated findings — never the recorded requests. That is the same rule the hosted product follows: only the engine’s findings reach a model.
• Errors are readable. A missing browser, an unreachable URL, a malformed capture or a rejected token come back as a sentence the agent can act on, never a stack trace.

Environment variables#

Related#

Prefer a command line or a CI job? The CLI runs the same engine locally and posts diffs on pull requests. Building your own integration? The HTTP API and its published OpenAPI spec are what the workspace tools here call.