# Server errors your agent can pick up over MCP

Page owner: Jaco Veldsman, hi@bugtape.ai. Last checked 10 November 2026.

This is the Node.js version of our [Streamlit cookbook](/blog/python-streamlit-bugtape-error-logs/). It covers a plain Node process, an Express API and a Next.js app, in that order. By the end, server errors land in BugTape as grouped issues with messages redacted by pattern, and your coding agent can read them over MCP.

## Checklist (5 minutes)

1. `npm install @bugtape/node`
2. Set `BUGTAPE_KEY` from **Setup → Node.js** in the console
3. Call `bugtape.init()` once at startup
4. Add the Express error handler or the Next.js `onRequestError` hook
5. Send one test message and open **Issues**

You need Node.js 20 or later. The package has no dependencies and works as ES modules or CommonJS.

## Install

```bash
npm install @bugtape/node
```

If your build can't reach the npm registry, install the same reviewed tarball from BugTape instead:

```bash
npm install https://app.bugtape.ai/sdk/node/bugtape-node-0.1.2.tgz
```

## Start any Node process

```js
import * as bugtape from '@bugtape/node';   // or: const bugtape = require('@bugtape/node')

bugtape.init({ service: 'api', release: process.env.GIT_SHA });
```

The key comes from the `BUGTAPE_KEY` environment variable (`bt_live_…` or `bt_test_…`). With no key, `init` logs one warning and reporting stays off, so a missing secret in a preview environment won't break anything.

From here BugTape reports uncaught exceptions, unhandled promise rejections (Node raises these as uncaught exceptions by default), and anything you pass in yourself:

```js
try {
  await runExport();
} catch (err) {
  bugtape.captureException(err);
  throw err;
}
```

**Crashes still crash.** Adding any `uncaughtException` listener switches off Node's default of printing the error and exiting with code 1. So when BugTape's listener is the only one, it reports the error, waits up to 2 seconds for delivery, then hands the error back to Node, and your process exits the way it did before with your original stack printed. If your app already has its own `uncaughtException` listener, that listener decides what happens.

Two things that trip people up:

- Reject with `Error` objects. A rejection with a plain value, such as a string, has no stack, so all such reports share one location. (More on this in [Node unhandled promise rejection](/guides/node-unhandled-promise-rejection/).)
- If you run Node with `--unhandled-rejections=warn` or `none`, or you listen for `unhandledRejection` yourself, rejections don't reach BugTape on their own. Call `bugtape.captureException(reason)` in your listener.

## Express

```js
app.use(routes);
app.use(bugtape.expressErrorHandler());   // after your routes, before your own error handlers
```

Errors that end in a 5xx are reported with the method and the route pattern, like `POST /api/invoices/:id`, not the concrete path. 4xx responses such as 404 are skipped. The error is passed on unchanged, so your own handler still answers the request. When no route matched, no path is sent at all, because a raw path can carry names.

If you're chasing a specific Express error, [Cannot set headers after they are sent](/guides/express-cannot-set-headers-after-sent/) walks through the usual cause.

## Next.js

Next.js 15 and later call `onRequestError` from `instrumentation.ts` for errors in pages, route handlers, server actions and middleware:

```ts
// instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') (await import('@bugtape/node')).init({ service: 'web' });
}

export async function onRequestError(...args: Parameters<typeof import('@bugtape/node').captureRequestError>) {
  if (process.env.NEXT_RUNTIME === 'nodejs') await (await import('@bugtape/node')).captureRequestError(...args);
}
```

Each report carries the route pattern (`/clients/[id]`) and the route type. Next's own redirect and not-found signals are skipped. `captureRequestError` waits up to 2 seconds so the report goes out before a serverless function is frozen.

The Edge runtime isn't supported, which is why both functions check `NEXT_RUNTIME`. For errors in the browser half of the same app, add the [browser SDK](/docs/quickstart/) too. If you already use Vercel MCP and want the agent to see those production browser errors, see [Vercel MCP and production browser errors](/guides/vercel-mcp-production-browser-errors/). Server component failures have their own guide: [Next.js server components render error](/guides/nextjs-server-components-render-error/).

## What leaves your server

| Sent | Never sent |
|---|---|
| Error type and a redacted message | Variable values |
| File, function, line and column of each frame | Source code lines |
| `cause` errors, each redacted | Request bodies, headers, cookies and query strings |
| Request method and route pattern (Express, Next.js) | Other environment variables |
| Your `service`, `release` and `environment` | |
| Datadog trace and span ids, when `dd-trace` is running | |

File paths are sent relative to the working directory, so your server layout stays private.

Redaction runs inside your process before anything is sent:

| Your message | What BugTape receives |
|---|---|
| `No rate for 'Acme Pty Ltd'` | `No rate for '[redacted]'` |
| `margin 4.25% for acct 18233` | `margin [num]% for acct [num]` |
| `Cannot read properties of undefined (reading 'map')` | unchanged (it's about code, not data) |

It also strips SQL statements, email addresses, bearer tokens, JWTs, URLs with credentials, storage paths, ids, IBANs, and values of pairs like `customer:` or `password=`. Values you pass in `extra` get the same treatment.

### What redaction misses

Redaction works by pattern, so a name dropped into a template string without quotes or digits gets through: `` new Error(`no rate for client ${name}`) `` is sent as `no rate for client Acme Pty Ltd`. For code like that, pick one:

```js
bugtape.init({
  service: 'api',
  extraRedactions: [[/\bACME-\d+\b/, '[account]']],
  beforeSend: (report) => (String(report.title).includes('healthcheck') ? null : report),
});
```

Or set `sendMessages: false` to send only the error type and location. The [privacy proof checklist](/docs/privacy-proof-checklist/) is the list to run before you point this at production.

## Grouping and releases

Repeats of the same error become one issue. The key is the error type, the redacted message, and the innermost frame in your own code (not `node_modules`). Because redaction removes the changing values, a timeout for account 18233 and one for account 20411 are the same issue, not two.

Give every report a release, or BugTape can't tell a fixed issue from a regression. If you don't pass `release`, the SDK picks up the commit from common CI and host variables such as `GITHUB_SHA`, `VERCEL_GIT_COMMIT_SHA` or `RENDER_GIT_COMMIT`. The full list is on [/docs/node/](/docs/node/#release).

## Serverless and scripts

Reports go out in the background and never keep the process alive on their own. In a serverless handler, or a script that calls `process.exit`, flush first:

```js
await bugtape.flush();   // true when every report since the last flush was accepted
```

BugTape never throws into your app and sends at most 30 reports a minute.

## Already on Datadog?

Keep it. If `dd-trace` is running, each BugTape issue carries the trace and span ids and links straight to the trace once you set your Datadog site in **Settings → Integrations → Datadog**. BugTape never loads or starts Datadog itself. See [Use BugTape with Datadog](/docs/datadog/).

## Check it

```bash
BUGTAPE_KEY=bt_test_… node --input-type=module -e "import * as b from '@bugtape/node'; b.init({ service: 'check' }); b.captureMessage('BugTape Node check');"
```

Then open **Issues** in the console. You should see "BugTape Node check". This only proves a report reaches BugTape from your machine; it doesn't test your Express or Next.js setup.

## Then hand it to your agent

Once errors land, connect BugTape to Claude Code, Cursor or Codex over MCP ([install guide](/blog/install-bugtape-mcp-claude-cursor-codex/)). When you ask your agent to look at production bugs, it reads the grouped issue, the redacted stack and the route through the [MCP tools](/docs/mcp-tools/), and can open a pull request for you to review. BugTape doesn't change your code, merge or deploy. You review and merge every fix.

## FAQ

### Does this replace my Sentry DSN?

No. `@bugtape/node` is its own SDK with its own `init`. If you want to compare the two, see [BugTape vs Sentry](/compare/sentry/).

### Does it work on the Next.js Edge runtime?

No. The Edge runtime isn't supported, and the hook above skips it. Routes on the Node.js runtime are reported as normal.

### Will it swallow crashes?

No. When BugTape's listener is the only `uncaughtException` listener, it reports, waits up to 2 seconds, then hands the error back to Node, so the process exits as it did before. If your own listener exists, it decides what happens.

### Are request bodies or headers ever sent?

No. Only the method and the route pattern are sent from Express and Next.js.

[Create a free account](/console/register) · [Node.js docs](/docs/node/) · [Python cookbook](/blog/python-streamlit-bugtape-error-logs/)
