Sentry — WebMCP Errors & Performance

One webmcp.configure for errors + performance. Hooks wrap only the agent path. See Analytics Overview and Step-by-Step.

For hook lifecycle, see Guide — Hooks. For types, see Reference — Hooks.

When to use

Sentry for error reporting and performance — captureException on error, startInactiveSpan on before/after, addBreadcrumb on denied.

External: Sentry Browser docs · @sentry/browser on npm

Step-by-step

Step 1 — Install & init Sentry

npm i @sentry/browser

import * as Sentry from '@sentry/browser';
Sentry.init({ dsn: 'https://...@o123.ingest.sentry.io/456', tracesSampleRate: 0.1 });

See Sentry — Install Browser JS.

Step 2 — Configure hooks once (global)

import * as Sentry from '@sentry/browser';
import { webmcp } from 'simple-webmcp';

webmcp.configure({
  hooks: {
    before: [({tool, invocationId, metadata})=>{
      metadata.sentrySpan = Sentry.startInactiveSpan({ name: `webmcp:${tool.tool.name}`, op: 'webmcp.execute' });
      Sentry.addBreadcrumb({ category:'webmcp', message:`invoked ${tool.tool.name} #${invocationId.slice(0,8)}`, level:'info' });
    }],
    after: [({metadata})=>{
      (metadata.sentrySpan as any)?.end();
    }],
    error: [({tool, error, input})=>{
      Sentry.captureException(error, { tags:{ tool: tool.tool.name }, extra:{ input } });
      ((Sentry as any).getCurrentScope?.().getSpan?.() as any)?.end?.();
    }],
    denied: [({tool, reason})=>{
      Sentry.addBreadcrumb({ category:'webmcp', message:`denied ${tool.tool.name}: ${reason}`, level:'info' });
    }],
  }
});

error and denied are observational — throwing inside them is swallowed (see Hooks — Error).

Step 3 — Verify in the demo

1. npm run docs:dev → open /demo.
2. Inspect → Invoke checkout → approve → check Sentry Performance → webmcp:checkout span.
3. Add a tool that throws → Invoke → check Sentry Issues → captureException with tool tag.
4. Toggle Require approval for checkout → Deny → check Breadcrumbs → denied checkout.

Step 4 — Production notes

• Sample rate: tracesSampleRate or tracesSampler for spans; avoid 100% in production.
• PII: Don't attach raw input with email/token to extra — redact first (see Hooks — After).
• Tenant: Enrich tags with tenantId via WebMCPProvider scoped before — see React.

Cross links

• Step-by-Step: Generic 4-step
• Overview: Analytics
• Guides: Hooks · React · Inspect
• Reference: Hooks · Errors
• Demo: /demo
• External: Sentry Browser · @sentry/browser

Troubleshooting

Symptom	Fix
No span in Performance	Ensure metadata.sentrySpan is set in before and .end() in after; check tracesSampleRate
Duplicate errors	Don't captureException in both error hook and fn — use hook only
Missing denied	denied runs only when before returns {action:'deny'} — see Hooks — Before

See also

• PostHog
• GA4
• Reference — Hooks