Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 4 additions & 10 deletions python/frameworks/mcp/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ Native MCP error spans can contain exception text and stack traces. The `FI_HIDE
Use Python 3.11–3.13. Install the published package and the MCP 1.x SDK:

```bash
pip install "traceAI-mcp>=0.1.3" "mcp>=1.8.1,<2"
pip install "traceAI-mcp>=0.1.3" "mcp>=1.30.0,<2"
```

Keep your existing application, agent, or model instrumentation to create spans. Configure its provider/exporter in both client and server processes. Enable MCP propagation in each process before importing transport functions:
Expand All @@ -26,17 +26,11 @@ from traceai_mcp import MCPInstrumentor
MCPInstrumentor().instrument()
```

The instrumentor connects existing spans; installing it alone will not create a request or tool span tree. Its package dependency remains `mcp>=1.8.1` for compatibility with existing applications, but new MCP 2.x setups should use the native route instead.
The instrumentor connects existing spans; installing it alone will not create a request or tool span tree. It requires `mcp>=1.30.0`; new MCP 2.x setups should use the native route instead.

### MCP 1.8.1 dependency compatibility
### Upgrading older MCP 1.x applications

MCP 1.8.1 uses a private Pydantic API that is absent in newer Pydantic releases. If you must stay on MCP 1.8.1, pin its compatible Pydantic dependency:

```bash
pip install "traceAI-mcp>=0.1.3" "mcp==1.8.1" "pydantic==2.11.10"
```

This pin applies only to MCP 1.8.1; do not impose it on newer SDK versions.
Upgrade the MCP SDK to at least 1.30.0 in both client and server environments. MCP 1.8.1 can close the session when a request is cancelled, preventing subsequent requests from completing. Pinning Pydantic resolves an import incompatibility in that older SDK, but does not fix cancellation. SDK versions below 1.30.0 are no longer supported by this instrumentor.

## Instrumentation lifecycle

Expand Down
243 changes: 234 additions & 9 deletions python/frameworks/mcp/poetry.lock

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion python/frameworks/mcp/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ classifiers = [
[tool.poetry.dependencies]
python = ">3.10, <3.14"
fi-instrumentation-otel = ">=0.1.11"
mcp = ">=1.8.1"
mcp = ">=1.30.0"


[tool.poetry.urls]
Expand Down
7 changes: 3 additions & 4 deletions python/frameworks/mcp/tests/constraints-floor.txt
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
# MCP 1.8.1 imports a private Pydantic API removed in newer releases.
# This is a tested floor matrix cell, not a package-wide runtime constraint.
mcp==1.8.1
pydantic==2.11.10
# Minimum supported MCP SDK, including request-cancellation liveness.
# Do not pin Pydantic to mask incompatibilities in older, unsupported SDKs.
mcp==1.30.0
47 changes: 47 additions & 0 deletions python/frameworks/mcp/tests/local_cancel_server.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
"""Real MCP server for the cancellation-followed-by-healthy-request regression."""
import asyncio
from importlib.metadata import version
import json
from pathlib import Path
import sys

from traceai_mcp import MCPInstrumentor


def main():
markers = Path(sys.argv[1])
if sys.argv[2] == "instrumented":
instrumentor = MCPInstrumentor()
instrumentor.instrument()
assert instrumentor.is_instrumented_by_opentelemetry

native = int(version("mcp").split(".")[0]) >= 2
if native:
from mcp.server.mcpserver import MCPServer as Server
else:
from mcp.server.fastmcp import FastMCP as Server

server = Server("cancellation-regression")

@server.tool()
async def hold() -> str:
# MCP 1.x requires an explicit protocol cancellation; MCP 2.x sends it
# when the client's call task is cancelled.
request_id = None if native else server.get_context().request_context.request_id
(markers / "started.json").write_text(json.dumps({"id": request_id}))
try:
await asyncio.sleep(60)
except asyncio.CancelledError:
(markers / "cancelled").touch()
raise
return "unexpected completion"

@server.tool()
async def echo() -> str:
return "healthy"

server.run(transport="stdio")


if __name__ == "__main__":
main()
56 changes: 56 additions & 0 deletions python/frameworks/mcp/tests/local_context_server.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
"""Real stdio transport consumer used by the context ownership regressions."""
import sys

import anyio
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor
from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter

from traceai_mcp import MCPInstrumentor

REMOTE_TRACE = 0x12345678901234567890123456789012
REMOTE_SPAN = 0x1234567812345678


async def main(reason, close):
exporter = InMemorySpanExporter()
provider = TracerProvider()
provider.add_span_processor(SimpleSpanProcessor(exporter))
tracer = provider.get_tracer("context-lifecycle")
instrumentor = MCPInstrumentor()
instrumentor.instrument()
import mcp.server.stdio as stdio

try:
with tracer.start_as_current_span("outer") as outer:
async with stdio.stdio_server() as (reader, writer):
with anyio.CancelScope() as scope:
async for _ in reader:
with tracer.start_as_current_span("request") as request:
assert request.get_span_context().trace_id == REMOTE_TRACE
if reason == "cancel":
scope.cancel()
await anyio.sleep(0)
raise AssertionError("cancellation was not delivered")
break
# Native stdio waits for its output pump on normal exit.
await writer.aclose()
if close == "explicit":
await reader.aclose()
with tracer.start_as_current_span("after_close") as after_close:
assert after_close.get_span_context().trace_id == outer.get_span_context().trace_id
with tracer.start_as_current_span("after_transport") as after:
assert after.get_span_context().trace_id == outer.get_span_context().trace_id
spans = {span.name: span for span in exporter.get_finished_spans()}
assert set(spans) == {"outer", "request", "after_transport"} | (
{"after_close"} if close == "explicit" else set()
) # Propagation must not add spans of its own.
assert spans["request"].parent.span_id == REMOTE_SPAN
assert spans["after_transport"].parent.span_id == outer.get_span_context().span_id
finally:
instrumentor.uninstrument()
provider.shutdown()


if __name__ == "__main__":
anyio.run(main, *sys.argv[1:])
Loading
Loading