What is Mcp Otel

mcp-otel is an example project that demonstrates distributed tracing using an MCP enabled agent. It showcases how to collect and visualize tracing data from various components of a system.

Use cases

Use cases for mcp-otel include debugging and performance optimization of distributed applications, monitoring service performance, and visualizing trace data for better insights into system behavior.

How to use

To use mcp-otel, set up the application as described in the README. The application includes a chat agent powered by Claude and multiple MCP Servers. Simply run the servers and interact with the agent to see tracing data being collected.

Key features

Key features of mcp-otel include distributed tracing with OpenTelemetry, support for multiple MCP Servers, and the ability to label spans by service name for better performance tracking.

Where to use

mcp-otel can be used in software development environments where distributed systems are implemented, particularly in applications that require monitoring and performance analysis.

MCP Distributed Tracing Example

This is an example project demonstrating how to do distributed tracing with an MCP enabled agent.

The application itself is a simple Claude powered chat agent in src/agent.ts. With multiple MCP Servers
in src/servers. These servers are run using the stdio transport but could be run remotely with no code changes.

Every component in the system emits opentelemetry data,
so any sink should be supported such as Datadog, Honeycomb, Signoz, etc.

Note: this is not meant to be production code and was thrown together to experiment with trace context propagation

Explanation

For each prompt, we start an otel trace and we collect spans until the “agent”
is done processing the response, then we end the trace. This might result in multiple tool calls, responses, errors, etc.

For each component in the system, we label the spans with a “service” name. Like so:

• Agent: mcp-agent-client
• Fetch Server: mcp-fetch-server
• Calc Server: mcp-calculator-server

Note: In a real world application, these service names would be meaningful to your application.

Example

Prompt:

Summarize the article on the top of Hacker News

This will make two tool calls to fetch which you can see in the trace:

Although we are looking at an agent trace, we can dig all the way down into the implementation details of fetch.

Having each span labeled by service also allows us to track on a service level how that MCP Server is performing:

Explanation

This requires no changes in the spec or the clients to work. But it creatively reuses the _meta property to shuttle the
trace context at the MCP protocol level.

This looks something like this when making the tool call:

const result = await this.client.callTool({
  name: toolUse.name,
  arguments: toolUse.arguments,
  _meta: {
    __traceContext: {
      // span here is the current span
      traceId: span.spanContext().traceId,
      spanId: span.spanContext().spanId,
      traceFlags: span.spanContext().traceFlags,
      isRemote: true
    }
  }
});

And like this when receiving on the server side:

const traceContext = extra._meta?.__traceContext;
// we then tell our SDK to use this trace context as the parent span

Running

For a simple way to collect and explore your otel data locally, run signoz using docker.

git clone -b main https://github.com/SigNoz/signoz.git
cd signoz/deploy/docker
docker compose up --remove-orphans -d

Then run the agent and chat with it:

export ANTHROPIC_API_KEY="sk-ant-******"
npm install
npm run build
npm start