Setup

Two parts: the SDK sends errors from your app, and the MCP server lets your coding agent read and resolve them. Prefer to delegate? Tell your agent: Read https://runheed.com/SETUP.txt and set up error tracking.

1. Create a project

Sign in, choose a plan, then create a project under Projects. Copy its DSN. It looks like runheed://pk_...@runheed.com/<project-id>. Store it as the RUNHEED_DSN environment variable.

2. Add the SDK

Node.js and TypeScript

terminalbash

npm install runheed

instrument.tstypescript

import runheed, { expressErrorHandler } from 'runheed';

runheed.init({
  dsn: process.env.RUNHEED_DSN,
  environment: process.env.NODE_ENV,
  release: process.env.GIT_SHA,
});

// Optional: which agent wrote and deployed this code
runheed.setAgent({ name: 'claude-code', sessionId: process.env.AGENT_SESSION_ID });

// Express: add after your routes
app.use(expressErrorHandler());

// Anywhere else
try {
  await chargeCard(order);
} catch (err) {
  runheed.captureException(err as Error, { orderId: order.id });
  throw err;
}

Python

app.pypython

import os, runheed

runheed.init(dsn=os.environ["RUNHEED_DSN"])
runheed.set_agent(name="claude-code", session_id=os.environ.get("AGENT_SESSION_ID"))

try:
    process(order)
except Exception as e:
    runheed.capture_exception(e)
    raise

Any language: HTTP

terminalbash

curl -X POST https://runheed.com/api/ingest \
  -H "X-Runheed-Key: pk_..." -H "Content-Type: application/json" \
  -d '{"errorType":"TimeoutError","errorMessage":"payment API timed out","environment":"production"}'

Responses: 200 stored, 401 bad key, 402 no active plan, 429 monthly limit reached or more than 300 events a minute for the project.

3. Connect your agent

Create an agent key in Settings (it is shown once), then add the MCP server.

Claude Code

terminalbash

claude mcp add runheed \
  -e RUNHEED_API_KEY=al_... -e RUNHEED_API_URL=https://runheed.com \
  -- npx -y runheed-mcp

Cursor, Claude Desktop and other MCP clients

mcp.jsonjson

{
  "mcpServers": {
    "runheed": {
      "command": "npx",
      "args": [
        "-y",
        "runheed-mcp"
      ],
      "env": {
        "RUNHEED_API_KEY": "al_...",
        "RUNHEED_API_URL": "https://runheed.com"
      }
    }
  }
}

Then ask your agent things like "what errors came in since the last deploy?" or "fix the top unresolved error and resolve it with the commit hash".

MCP tools

runheed_search_errors	Search errors by text, status or project
runheed_get_recent	Most recent errors
runheed_get_error	Full details: stack trace, breadcrumbs, agent context
runheed_get_error_context	Environment, user, agent, request and extra data
runheed_get_trends	Counts and top errors for 24h, 7d or 30d
runheed_get_project_health	0 to 100 health score with recommendations
runheed_resolve_error	Mark resolved with a comment, e.g. the fixing commit
runheed_ignore_error / runheed_unignore_error	Silence or restore an error

Limits and data

Events count per workspace per calendar month (UTC). You get an email at 80% and 100%.
Each project accepts up to 300 events a minute; extra events get a 429 with Retry-After.
History follows your plan (30, 90 or 180 days). The 100 newest full events are kept per grouped error; counts stay exact.
Authorization, cookie and API-key request headers are redacted on arrival.