feat(core): MCP server instrumentation without breaking Miniflare

[betegon]

Closes #16826, #16654, #16666

Different approach from #16807 .

Using Proxy was causing issues in cloudflare #16182.

Now using fill we shouldn't have those problems as fill doesn't create a new wrapper object with a different identity, so now:

1. fill just replaces the method on the existing object
2. The transport object keeps its original identity
3. When transport.start() runs and accesses private fields, this is still the original transport object
4. The WeakMap recognizes it as the same object that owns the private fields

What's inside

• Support for new MCP SDK methods (mcpServerInstance.tool(), mcpServerInstance.resource(), etc.)
• Tracing instrumentation
• Error handling

Tracing

It follows OTEL semantic conventions for MCP and adds more attributes we thought are useful.

It also handles PII based on user setting of sendDefaultPii.

Tracing flow

1. Transport receives tools/call request (id: 2)
2. Create INACTIVE mcp.server span
3. Store span inrequestIdToSpanMap[2] = { span, method: "tools/call", startTime }
4. Execute handler with span context (handler gets requestId: 2)
5. Handler finds span using requestId: 2
6. Tool execution happens within span context
7. Response sent with tool results
8. completeSpanWithToolResults(2, result) enriches and completes span

Error handling

1. error capture - errorCapture.ts

• Non-invasive error reporting that never interferes with MCP service operation
• Error context with MCP-specific metadata
• PII filtering respects sendDefaultPii settings
• Resilient to Sentry failures (wrapped in try-catch)

2. Tool execution error capturing - handlers.ts

• Captures exceptions thrown during tool execution
• Preserves normal MCP behaviour (errors converted to isError: true)
• Includes tool name, arguments, and request context
• Handles both sync and async tool handlers

3. Transport error instrumentation - transport.ts

• Captures connection errors and network failures
• Intercepts JSON-RPC error responses
• Includes transport type and session information
• Handles error responses being sent back to clients

[AbhiPrasad]

Very nice, all good from my eyes in overall direction!

[betegon]

Thanks @AbhiPrasad! Will keep working on this and close the other PR using Proxy. Will apply your suggestions here!

[AbhiPrasad]

1st pass.

Before I review further, I'd like to see the develop docs PR so that I can make sure all the attributes are being added as we expect. Right now it's a bit hard to know if an attribute is missing or not.

I assume much of this is AI generated, which is fine, but let's make sure we clean the comments up (and expand the jsdoc string appropriately).

[AbhiPrasad]

Are these vendored in from the mcp package? If so we need to put the mcp library license + sha we grabbed the types from in this file.

[AbhiPrasad]

m: Instead of inline comments like this, I would prefer if we added notes in the jsdoc to document behaviour. Right now this comment is a bit redundant with the code.

Ditto with other instances of this.

[AbhiPrasad]

l: I would prefer if we called reduce on Object.entries(spanData) to do this operation instead of calling filter + Object.fromEntries on the constructed array.

[AbhiPrasad]

The sdk should not be setting tags by default. Tags are meant to be only set by users.

What we can instead do is set a mechanism: https://develop.sentry.dev/sdk/data-model/event-payloads/exception/#exception-mechanism.

[AbhiPrasad]

Let's add an example usage snippet to the jsdoc here.

[betegon]

@AbhiPrasad wdyt of this? Bugbot said that wrapTransportOnMessage, wrapTransportSend, etc. only work if the transport methods are defined at connect() time, and that the fill doesn’t capture handlers set lazy after that.

From what I’ve tested, fill works fine. the MCP server sets onmessage, send... during .connect() (coed here), and wrapMcpServerWithSentry() is called before that, so the methods are already in place when we wrap them.

Do you think it makes sense to get lazy loading handlers? Not sure if it’s worthy adding more complexity for this. Cursor suggested something like a wrapTransportProperty helper that uses property descriptors like:

function wrapTransportProperty(obj, key, wrapFn) {
  let current = obj[key];
  let wrapped = false;

  Object.defineProperty(obj, key, {
    configurable: true,
    enumerable: true,
    get() {
      return current;
    },
    set(newValue) {
      if (typeof newValue === 'function' && !wrapped) {
        current = wrapFn(newValue);
        wrapped = true;
      } else {
        current = newValue;
        wrapped = false;
      }
    }
  });

  // in case the property was already assigned before wrapping
  if (typeof current === 'function') {
    obj[key] = current;
  }
}

[AbhiPrasad]

only work if the transport methods are defined at connect() time, and that the fill doesn’t capture handlers set lazy after that

yeah as long as it exists when we wrap it I think we are fine.

[cursor]

Bug: Session ID Missing Causes Span Collisions

The requestIdToSpanMap is now keyed solely by requestId. Since requestIds are only guaranteed to be unique per session and are frequently reused across different MCP sessions, this leads to collisions. When multiple concurrent sessions use the same requestId, the second request overwrites the first session's span data. This results in:

• Incorrect span-to-handler correlation and attribute assignment.
• Premature termination or loss of spans from the original session.
• Unreliable tracing data in multi-session environments.

Additionally, cleanupAllPendingSpans(), invoked when a single transport closes, clears the entire global map, prematurely ending and marking as error all spans, including those belonging to other still-active sessions. This is a regression from the previous implementation which used (sessionId, requestId) for correlation, preventing these issues.

packages/core/src/integrations/mcp-server/correlation.ts#L15-L129

sentry-javascript/packages/core/src/integrations/mcp-server/correlation.ts

Lines 15 to 129 in 790f2b3

	import { filterMcpPiiFromSpanData } from './piiFiltering';
	import type { RequestId, SessionId } from './types';
	// Simplified correlation system that works with or without sessionId
	// Maps requestId directly to span data for stateless operation
	const requestIdToSpanMap = new Map<
	RequestId,
	{
	span: Span;
	method: string;
	startTime: number;
	}
	>();
	/**
	* Stores span context for later correlation with handler execution
	*/
	export function storeSpanForRequest(requestId: RequestId, span: Span, method: string): void {
	requestIdToSpanMap.set(requestId, {
	span,
	method,
	startTime: Date.now(),
	});
	}
	/**
	* Associates handler execution with the corresponding request span
	*/
	export function associateContextWithRequestSpan<T>(
	extraHandlerData: { sessionId?: SessionId; requestId: RequestId } | undefined,
	cb: () => T,
	): T {
	if (extraHandlerData) {
	const { requestId } = extraHandlerData;
	const spanData = requestIdToSpanMap.get(requestId);
	if (!spanData) {
	return cb();
	}
	// Keep span in map for response enrichment (don't delete yet)
	return withActiveSpan(spanData.span, () => {
	return cb();
	});
	}
	return cb();
	}
	/**
	* Completes span with tool results and cleans up correlation
	*/
	export function completeSpanWithResults(requestId: RequestId, result: unknown): void {
	const spanData = requestIdToSpanMap.get(requestId);
	if (spanData) {
	const { span, method } = spanData;
	const spanWithMethods = span as Span & {
	setAttributes: (attrs: Record<string, unknown>) => void;
	setStatus: (status: { code: number; message: string }) => void;
	end: () => void;
	};
	if (spanWithMethods.setAttributes && method === 'tools/call') {
	// Add tool-specific attributes with PII filtering
	const rawToolAttributes = extractToolResultAttributes(result);
	const client = getClient();
	const sendDefaultPii = Boolean(client?.getOptions().sendDefaultPii);
	const toolAttributes = filterMcpPiiFromSpanData(rawToolAttributes, sendDefaultPii);
	spanWithMethods.setAttributes(toolAttributes);
	const isToolError = rawToolAttributes[MCP_TOOL_RESULT_IS_ERROR_ATTRIBUTE] === true;
	if (isToolError) {
	spanWithMethods.setStatus({
	code: 2, // ERROR
	message: 'Tool execution failed',
	});
	captureError(new Error('Tool returned error result'), 'tool_execution');
	}
	}
	if (spanWithMethods.end) {
	spanWithMethods.end();
	}
	requestIdToSpanMap.delete(requestId);
	}
	}
	/**
	* Cleans up all pending spans (for transport close)
	*/
	export function cleanupAllPendingSpans(): number {
	const pendingCount = requestIdToSpanMap.size;
	for (const [, spanData] of requestIdToSpanMap) {
	const spanWithEnd = spanData.span as Span & {
	end: () => void;
	setStatus: (status: { code: number; message: string }) => void;
	};
	if (spanWithEnd.setStatus && spanWithEnd.end) {
	spanWithEnd.setStatus({
	code: 2, // ERROR
	message: 'Transport closed before request completion',
	});
	spanWithEnd.end();
	}
	}
	requestIdToSpanMap.clear();
	return pendingCount;
	}

Fix in Cursor • Fix in Web

---

Was this report helpful? Give feedback by reacting with 👍 or 👎