feat: enable tracing for tool executions through mcp server (#12804)

## Description

<!-- Provide a brief description of the changes in this PR -->
The Pr udpates core tool to create a default span if not passed , which
enables tracing for all core tool executions
one of output is Observability section in UI , traces are now logged
during execution of mcp server tools
## Related Issue(s)

<!-- Link to the issue(s) this PR addresses, using hashtag notation:
Fixes #123 -->
## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Test update

## Checklist

- [ ] I have made corresponding changes to the documentation (if
applicable)
- [ ] I have added tests that prove my fix is effective or that my
feature works


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* MCP server tool executions now generate observable traces that appear
in the Observability UI, providing enhanced visibility into tool
performance and execution flow.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Daniel Lew <danielshlomolew@gmail.com>
Co-authored-by: Daniel Lew <51924260+DanielSLew@users.noreply.github.com>
Co-authored-by: Eric Pinzur <2641606+epinzur@users.noreply.github.com>

Author: 3 people

.changeset/floppy-paths-do.md

@@ -0,0 +1,6 @@
+---
+'@mastra/core': minor
+---
+Enabled tracing for tool executions through mcp server
+
+Traces now appear in the Observability UI for MCP server tool calls

observability/mastra/src/integration-tests.test.ts

@@ -4,7 +4,7 @@ import type { StructuredOutputOptions } from '@mastra/core/agent';
 import type { MastraDBMessage } from '@mastra/core/agent/message-list';
 import { RequestContext } from '@mastra/core/di';
 import { Mastra } from '@mastra/core/mastra';
-import { SpanType } from '@mastra/core/observability';
+import { SpanType, EntityType, getOrCreateSpan, executeWithContext } from '@mastra/core/observability';
 import type { TracingContext } from '@mastra/core/observability';
 
 // Core Mastra imports
@@ -1838,4 +1838,73 @@ describe('Tracing Integration Tests', () => {
       finalExpectations(testExporter);
     });
   });
+
+  describe('Standalone tool execution tracing (MCP-style)', () => {
+    it('should create a root span when tool is executed without a parent span context', async () => {
+      const testExporter = new TestExporter();
+
+      const simpleTool = createTool({
+        id: 'standalone-tool',
+        description: 'A tool executed without an agent',
+        inputSchema: z.object({ value: z.number() }),
+        outputSchema: z.object({ doubled: z.number() }),
+        execute: async inputData => {
+          return { doubled: inputData.value * 2 };
+        },
+      });
+
+      const mastra = new Mastra({
+        ...getBaseMastraConfig(testExporter),
+        tools: { 'standalone-tool': simpleTool },
+      });
+
+      // Simulate standalone tool execution (e.g. MCP server calling a tool directly)
+      // by using getOrCreateSpan with no tracingContext.currentSpan
+      const selectedInstance = mastra.observability.getSelectedInstance({});
+      expect(selectedInstance).toBeDefined();
+      expect(typeof selectedInstance!.startSpan).toBe('function');
+
+      const toolSpan = getOrCreateSpan({
+        type: SpanType.TOOL_CALL,
+        name: "tool: 'standalone-tool'",
+        input: { value: 5 },
+        entityType: EntityType.TOOL,
+        entityId: 'standalone-tool',
+        entityName: 'standalone-tool',
+        attributes: {
+          toolDescription: 'A tool executed without an agent',
+          toolType: 'tool',
+        },
+        tracingContext: { currentSpan: undefined },
+        mastra,
+      });
+
+      expect(toolSpan).toBeDefined();
+
+      // Execute within the span context and complete it
+      const result = await executeWithContext({
+        span: toolSpan!,
+        fn: async () => {
+          return { doubled: 10 };
+        },
+      });
+
+      toolSpan!.end({ output: result });
+
+      // Flush the observability bus to ensure async export handlers complete
+      await selectedInstance!.getObservabilityBus().flush();
+
+      expect(result).toEqual({ doubled: 10 });
+
+      // Verify a TOOL_CALL span was created as a root span
+      const toolSpans = testExporter.getSpansByType(SpanType.TOOL_CALL);
+      expect(toolSpans).toHaveLength(1);
+      expect(toolSpans[0]?.name).toBe("tool: 'standalone-tool'");
+      expect(toolSpans[0]?.traceId).toBeDefined();
+
+      // Verify no incomplete spans
+      const incompleteSpans = testExporter.getIncompleteSpans();
+      expect(incompleteSpans).toHaveLength(0);
+    });
+  });
 });

observability/mastra/src/spans/default.ts

@@ -153,34 +153,34 @@ export class DefaultSpan<TType extends SpanType> extends BaseSpan<TType> {
 /**
  * Generate OpenTelemetry-compatible span ID (64-bit, 16 hex chars)
  */
-function generateSpanId(): string {
-  // Generate 8 random bytes (64 bits) in hex format
-  const bytes = new Uint8Array(8);
-  if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
-    crypto.getRandomValues(bytes);
-  } else {
-    // Fallback for environments without crypto.getRandomValues
-    for (let i = 0; i < 8; i++) {
-      bytes[i] = Math.floor(Math.random() * 256);
+function fillRandomBytes(bytes: Uint8Array): void {
+  try {
+    // Use Web Crypto API with proper this binding
+    const webCrypto = globalThis.crypto;
+    if (webCrypto?.getRandomValues) {
+      webCrypto.getRandomValues.call(webCrypto, bytes);
+      return;
     }
+  } catch {
+    // Fall through to fallback
   }
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = Math.floor(Math.random() * 256);
+  }
+}
+
+function generateSpanId(): string {
+  const bytes = new Uint8Array(8);
+  fillRandomBytes(bytes);
   return Array.from(bytes, byte => byte.toString(16).padStart(2, '0')).join('');
 }
 
 /**
  * Generate OpenTelemetry-compatible trace ID (128-bit, 32 hex chars)
  */
 function generateTraceId(): string {
-  // Generate 16 random bytes (128 bits) in hex format
   const bytes = new Uint8Array(16);
-  if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
-    crypto.getRandomValues(bytes);
-  } else {
-    // Fallback for environments without crypto.getRandomValues
-    for (let i = 0; i < 16; i++) {
-      bytes[i] = Math.floor(Math.random() * 256);
-    }
-  }
+  fillRandomBytes(bytes);
   return Array.from(bytes, byte => byte.toString(16).padStart(2, '0')).join('');
 }
 

packages/core/src/tools/tool-builder/builder.e2e.test.ts

@@ -609,6 +609,8 @@ describe('Tool Tracing Context Injection', () => {
       entityType: 'tool',
       requestContext: new RequestContext(),
       tracingPolicy: undefined,
+      mastra: undefined,
+      metadata: {},
     });
 
     // Verify tracingContext was injected with the tool span
@@ -623,7 +625,7 @@ describe('Tool Tracing Context Injection', () => {
     expect(result).toEqual({ result: 'processed: test' });
   });
 
-  it('should not inject tracingContext when agentSpan is not available', async () => {
+  it('should not inject tracingContext when agentSpan is not available and no observability configured', async () => {
     let receivedTracingContext: any = undefined;
 
     const testTool = createTool({
@@ -655,7 +657,7 @@ describe('Tool Tracing Context Injection', () => {
     const builtTool = builder.build();
     const result = await builtTool.execute!({ message: 'test' }, { toolCallId: 'test-call-id', messages: [] });
 
-    // Verify tracingContext was injected but currentSpan is undefined
+    // Verify tracingContext was injected but currentSpan is undefined (no observability configured)
     expect(receivedTracingContext).toEqual({ currentSpan: undefined });
     expect(result).toEqual({ result: 'processed: test' });
   });
@@ -716,6 +718,8 @@ describe('Tool Tracing Context Injection', () => {
       entityType: 'tool',
       requestContext: new RequestContext(),
       tracingPolicy: undefined,
+      mastra: undefined,
+      metadata: {},
     });
 
     // Verify Vercel tool execute was called (without tracingContext)
@@ -837,6 +841,8 @@ describe('Tool Tracing Context Injection', () => {
       entityType: 'tool',
       requestContext: new RequestContext(),
       tracingPolicy: undefined,
+      mastra: undefined,
+      metadata: {},
     });
   });
 });

packages/core/src/tools/tool-builder/builder.ts

@@ -11,9 +11,17 @@ import {
   jsonSchema,
 } from '@mastra/schema-compat';
 import { z } from 'zod/v4';
+import { Mastra } from '../..';
 import { MastraBase } from '../../base';
 import { ErrorCategory, MastraError, ErrorDomain } from '../../error';
-import { SpanType, wrapMastra, executeWithContext, EntityType, createObservabilityContext } from '../../observability';
+import {
+  SpanType,
+  wrapMastra,
+  executeWithContext,
+  EntityType,
+  getOrCreateSpan,
+  createObservabilityContext,
+} from '../../observability';
 import { RequestContext } from '../../request-context';
 import { isStandardSchemaWithJSON, toStandardSchema, standardSchemaToJSONSchema } from '../../schema';
 import { isVercelTool } from '../../tools/toolchecks';
@@ -321,9 +329,9 @@ export class CoreToolBuilder extends MastraBase {
       // Fall back to build-time context for Legacy methods (AI SDK v4 doesn't support passing custom options)
       const tracingContext = execOptions.tracingContext || options.tracingContext;
 
-      // Create tool span if we have a current span available
+      // Create tool span - either as child of existing span or as new root span (e.g. MCP tools)
       const toolRequestContext = execOptions.requestContext ?? options.requestContext;
-      const toolSpan = tracingContext?.currentSpan?.createChildSpan({
+      const toolSpan = getOrCreateSpan({
         type: SpanType.TOOL_CALL,
         name: `tool: '${options.name}'`,
         input: args,
@@ -335,7 +343,9 @@ export class CoreToolBuilder extends MastraBase {
           toolType: logType || 'tool',
         },
         tracingPolicy: options.tracingPolicy,
+        tracingContext: tracingContext,
         requestContext: toolRequestContext,
+        mastra: options.mastra instanceof Mastra ? options.mastra : undefined,
       });
 
       try {