Add OpenTelemetry instrumentation for Model Context Protocol (MCP) by lukeina2z · Pull Request #3822 · open-telemetry/opentelemetry-python-contrib

lukeina2z · 2025-10-09T16:10:16Z

Description

This commit introduces a new instrumentation package for the Model Context
Protocol (MCP), enabling automatic distributed tracing for MCP client-server
interactions.

Key Features:

Automatic instrumentation of MCP client sessions and server handlers
Support for both stdio and HTTP/SSE transports
W3C trace context propagation across MCP messages
Comprehensive span attributes following semantic conventions
Tool calls, resource reads, prompt handling, and session lifecycle tracing

Package Structure:

Core instrumentation: McpInstrumentor with automatic wrapping
Semantic attributes: MCP-specific span attributes and conventions
Test coverage: Unit tests for instrumentor, server, and session wrappers
Examples: stdio (simple-client-server) and HTTP/SSE transport demos
Documentation: README, CHANGELOG, and example-specific guides

Technical Implementation:

Wraps mcp.ClientSession and mcp.server.Server classes
Injects trace context into message metadata
Extracts and propagates context across transport boundaries
Records exceptions and sets span status appropriately
Requires Python >=3.10 (MCP SDK requirement)

MCP semantic conventions
open-telemetry/semantic-conventions#2083
https://github.com/lmolkova/semantic-conventions/blob/mcp/docs/gen-ai/mcp.md

Examples:

simple-client-server: stdio transport with tool calls and resources
http-transport: HTTP/SSE transport with distributed tracing
Both include Jaeger trace visualizations and setup instructions"

Type of change

Please delete options that are not relevant.

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
This change requires a documentation update

How Has This Been Tested?

Unit tests added.
tox -e py310-test-instrumentation-mcp-oldest
tox -e py310-test-instrumentation-mcp-latest
tox -e py311-test-instrumentation-mcp-oldest
tox -e py311-test-instrumentation-mcp-latest
tox -e py312-test-instrumentation-mcp-oldest
tox -e py312-test-instrumentation-mcp-latest
tox -e py313-test-instrumentation-mcp-oldest
tox -e py313-test-instrumentation-mcp-latest
tox -e pypy3-test-instrumentation-mcp-oldest
tox -e pypy3-test-instrumentation-mcp-latest

tox -e lint-instrumentation-mcp
tox -e spellcheck
tox -e ruff
End to end testing with two applications in the examples folder.

Does This PR Require a Core Repo Change?

Yes. - Link to PR:
No.

Checklist:

See contributing.md for styleguide, changelog guidelines, and more.

Followed the style guidelines of this project
Changelogs have been updated
Unit tests have been added
Documentation has been updated

This commit introduces a new instrumentation package for the Model Context Protocol (MCP), enabling automatic distributed tracing for MCP client-server interactions. Key Features: - Automatic instrumentation of MCP client sessions and server handlers - Support for both stdio and HTTP/SSE transports - W3C trace context propagation across MCP messages - Comprehensive span attributes following semantic conventions - Tool calls, resource reads, prompt handling, and session lifecycle tracing Package Structure: - Core instrumentation: McpInstrumentor with automatic wrapping - Semantic attributes: MCP-specific span attributes and conventions - Test coverage: Unit tests for instrumentor, server, and session wrappers - Examples: stdio (simple-client-server) and HTTP/SSE transport demos - Documentation: README, CHANGELOG, and example-specific guides Technical Implementation: - Wraps mcp.ClientSession and mcp.server.Server classes - Injects trace context into message metadata - Extracts and propagates context across transport boundaries - Records exceptions and sets span status appropriately - Requires Python >=3.10 (MCP SDK requirement) CI/CD Updates: - Added MCP instrumentation to test workflows - Updated lint configuration for new package - Disabled pypy3 tests (Python 3.10+ requirement) - Integrated into eachdist.ini and bootstrap generation Examples: - simple-client-server: stdio transport with tool calls and resources - http-transport: HTTP/SSE transport with distributed tracing - Both include Jaeger trace visualizations and setup instructions"

xrmx · 2025-10-15T13:24:37Z

instrumentation-genai/opentelemetry-instrumentation-mcp/pyproject.toml

+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3",


We drop python version 6 months after they have been EOL'ed. So Python 3.9 should be there.

The MCP Python SDK does not support Python 3.9. Should the instrumentation library support Python 3.9?
https://github.com/modelcontextprotocol/python-sdk/blob/main/pyproject.toml#L18

xrmx

Are you in touch with the genai WG people? From a quick look it looks like this needs semantic conventions attributes that are not spec'ed it.

...enai/opentelemetry-instrumentation-mcp/src/opentelemetry/instrumentation/mcp/instrumentor.py

mxiamxia · 2025-10-15T22:02:43Z

...enai/opentelemetry-instrumentation-mcp/src/opentelemetry/instrumentation/mcp/instrumentor.py

+    _CLIENT_SPAN_NAME = "mcp.client"
+    _SERVER_SPAN_NAME = "mcp.server"


are these defined by MCP semconv? shoud these be moved to attributes.py as well?

These two constants are used to build span names, but they are not span names.
https://github.com/lmolkova/semantic-conventions/blob/mcp/docs/gen-ai/mcp.md

mxiamxia · 2025-10-15T22:04:55Z

...enai/opentelemetry-instrumentation-mcp/src/opentelemetry/instrumentation/mcp/instrumentor.py

+            tracer_provider: Optional tracer provider to use
+            propagators: Optional propagators for context injection/extraction
+        """
+        _LOG.info("Initializing MCP instrumentor xyxyxy")


is this info logging needed? if yes, need to fix logging message content

mxiamxia · 2025-10-15T22:09:43Z

...enai/opentelemetry-instrumentation-mcp/src/opentelemetry/instrumentation/mcp/instrumentor.py

+
+    def instrumentation_dependencies(self) -> Collection[str]:
+        """Return the dependencies required for this instrumentation."""
+        return ("mcp >= 1.8.1",)


any reason why the support starts from this version

That's the start of the new protocol:
https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.8.0
This is the first release supporting the new Streamable HTTP transport from protocol version 2025-03-26, which supersedes the SSE transport from protocol version 2024-11-05. 🎉

mxiamxia · 2025-10-15T22:21:28Z

...enai/opentelemetry-instrumentation-mcp/src/opentelemetry/instrumentation/mcp/instrumentor.py

+            message_json = message.model_dump(
+                by_alias=True, mode="json", exclude_none=True
+            )


is a try/catch error handling required to not interupt the original request?

It's in try-except block now. Original call will be invoked explicitly if exception happens.

lukeina2z · 2025-10-20T19:07:51Z

Are you in touch with the genai WG people? From a quick look it looks like this needs semantic conventions attributes that are not spec'ed it.

This is their PR:
MCP semantic conventions
open-telemetry/semantic-conventions#2083

punitmahes · 2026-01-13T17:30:01Z

@lukeina2z Any timelines for this PR?
also, I see that this PR doesn't implment anything on the metrics front. Is there any plans to integrate metrics as well?
if yes, I would be happy to contribute.

shuwpan · 2026-01-15T23:50:00Z

...enai/opentelemetry-instrumentation-mcp/src/opentelemetry/instrumentation/mcp/instrumentor.py

+        def hook(_module: Any) -> None:
+            wrap_function_wrapper(module, target, wrapper)
+
+        register_post_import_hook(hook, module)


question: Hi @lukeina2z, I’m still new to the repo and trying to learn the patterns here. I noticed that in other places wrap_function_wrapper is used directly, while here it’s combined with register_post_import_hook. Could you help me understand why this approach is preferred in this case? Thanks!

shuwpan · 2026-01-16T00:16:42Z

...enai/opentelemetry-instrumentation-mcp/src/opentelemetry/instrumentation/mcp/instrumentor.py

+
+class McpInstrumentor(BaseInstrumentor):
+    """
+    Instrumentor for MCP (Model Context Protocol).


nit: I noticed the Instrumentor class has many methods (~450 lines). Other instrumentations like openai-v2 split wrapper logic into separate files (e.g., patch.py, utils.py). Would it make sense to follow that pattern here for consistency?

aabmass · 2026-02-12T23:10:57Z

@lukeina2z are you still working on this PR? Any reason to open this separate PR when #3678 is already open?

lukeina2z requested a review from a team as a code owner October 9, 2025 16:10

github-actions bot assigned codefromthecrypt, karthikscale3, lzchen and nirga Oct 9, 2025

lukeina2z changed the title ~~Add OpenTelemetry instrumentation for MCP (Model Context Protocol)~~ [WIP] Add OpenTelemetry instrumentation for MCP (Model Context Protocol) Oct 13, 2025

lukeina2z marked this pull request as draft October 13, 2025 01:49

lukeina2z force-pushed the mcp-prfoo branch 4 times, most recently from 0775d46 to ba43d31 Compare October 14, 2025 05:59

github-actions bot assigned lmolkova Oct 14, 2025

lukeina2z changed the title ~~[WIP] Add OpenTelemetry instrumentation for MCP (Model Context Protocol)~~ Add OpenTelemetry instrumentation for Model Context Protocol (MCP) Oct 14, 2025

lukeina2z force-pushed the mcp-prfoo branch 3 times, most recently from bba04fc to 36a82f4 Compare October 14, 2025 17:30

lukeina2z marked this pull request as ready for review October 14, 2025 17:30

lukeina2z force-pushed the mcp-prfoo branch 3 times, most recently from 4bcb845 to 10f1f8f Compare October 14, 2025 21:44

lukeina2z force-pushed the mcp-prfoo branch from 10f1f8f to 2a4793c Compare October 14, 2025 21:46

xrmx reviewed Oct 15, 2025

View reviewed changes

lukeina2z mentioned this pull request Oct 15, 2025

feat(instrumentation-mcp): add OpenTelemetry instrumentation for MCP SDK open-telemetry/opentelemetry-js-contrib#3175

Closed

mxiamxia reviewed Oct 15, 2025

View reviewed changes

...enai/opentelemetry-instrumentation-mcp/src/opentelemetry/instrumentation/mcp/instrumentor.py Show resolved Hide resolved

mxiamxia reviewed Oct 15, 2025

View reviewed changes

Merge branch 'main' into mcp-prfoo

af5b462

Luke Zhang added 4 commits October 20, 2025 12:23

rename instrumentation.py to instrumentor.py

2a50ef7

Protect model_dump() call with try-except block.

0e7b333

running tox -e generate-workflows

96c6c10

put model_validate in a try-except block.

3f852df

shuwpan reviewed Jan 15, 2026

View reviewed changes

shuwpan reviewed Jan 16, 2026

View reviewed changes

lukeina2z closed this by deleting the head repository Mar 7, 2026

		_CLIENT_SPAN_NAME = "mcp.client"
		_SERVER_SPAN_NAME = "mcp.server"

Conversation

lukeina2z commented Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change

How Has This Been Tested?

Does This PR Require a Core Repo Change?

Checklist:

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xrmx left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mxiamxia Oct 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mxiamxia Oct 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lukeina2z commented Oct 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

punitmahes commented Jan 13, 2026

Uh oh!

shuwpan Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shuwpan Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aabmass commented Feb 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

11 participants

lukeina2z commented Oct 9, 2025 •

edited

Loading

mxiamxia Oct 15, 2025 •

edited

Loading

mxiamxia Oct 15, 2025 •

edited

Loading

lukeina2z commented Oct 20, 2025 •

edited

Loading

shuwpan Jan 15, 2026 •

edited

Loading

shuwpan Jan 16, 2026 •

edited

Loading