π The fast, Pythonic way to build MCP servers and clients.
Emit one SERVER span per request and adopt spec-correct error codes (#4445)
Jeremiah Lowinac78e6f69342
diff --git a/docs/development/v4-notes/change-register.mdx b/docs/development/v4-notes/change-register.mdxindex bd8e94ee5..4e0a6f57b 100644--- a/docs/development/v4-notes/change-register.mdx+++ b/docs/development/v4-notes/change-register.mdx@@ -146,6 +146,18 @@ Resources and prompts have **no `task` field** on their params in b1, so task-au*Verify:* `fastmcp_slim/fastmcp/_sdk_patches.py`, `server/tasks/*`.+### Single SERVER span per request β Absorbed (post-migration fix)++SDK v2 seeds an `OpenTelemetryMiddleware` into every lowlevel `Server`, so each inbound request already emits a SERVER span. FastMCP emits its own richer SERVER span per request (with `fastmcp.*` and auth/session attributes), so a server with an OTel exporter installed would export **two** SERVER spans per request under different attribute conventions. `LowLevelServer.__init__` now drops the SDK's seeded `OpenTelemetryMiddleware` (matched by type, not position, leaving any other seeded middleware intact) and keeps FastMCP's spans. Inbound W3C trace-context extraction is unaffected β FastMCP's telemetry reads `traceparent` from `_meta` itself, so distributed traces still link client to server. Client-side is not double-counted: the SDK's `ClientSession` emits a low-level `MCP send <method>` CLIENT span that nests *under* FastMCP's high-level client span, a legitimate parent/child hierarchy rather than a duplicate.++*Verify:* `fastmcp_slim/fastmcp/server/low_level.py` (the `OpenTelemetryMiddleware` filter); `tests/server/telemetry/test_server_tracing.py::TestSingleServerSpan`.++### Spec-correct error codes via a central translator β Breaking (wire error code)++Resource-not-found responses from the core `resources/read` handler previously used `-32002`. SEP-2164 (and the SDK's own mcpserver, which maps `ResourceNotFoundError` β `INVALID_PARAMS`) makes this `-32602`. The per-adapter `MCPError(code=..., ...)` literals in `server/mixins/mcp_operations.py` are replaced by a single `fastmcp.exceptions.to_mcp_error()` translator that maps FastMCP's public exceptions to the `mcp_types` code constants (`NotFoundError`/`DisabledError`/`ValidationError` β `INVALID_PARAMS`, else `INTERNAL_ERROR`). Clients that string-matched on the old `-32002` for resource-not-found must switch to `-32602`; the human-readable message ("Resource not found: ...") is unchanged. The opt-in `ErrorHandlingMiddleware`, which has its own documented per-method-prefix code mapping, is intentionally left as-is.++*Verify:* `fastmcp_slim/fastmcp/exceptions.py` (`to_mcp_error`); `fastmcp_slim/fastmcp/server/mixins/mcp_operations.py`; `tests/test_exceptions.py`.+## ClientThe `fastmcp.Client` public API is preserved exactly. The client stays a wrapper around `mcp.ClientSession` in legacy/handshake mode; the first-class `mcp.client.Client` is deliberately not adopted in this PR.diff --git a/fastmcp_slim/fastmcp/exceptions.py b/fastmcp_slim/fastmcp/exceptions.pyindex e3c831ba9..fb6571f05 100644--- a/fastmcp_slim/fastmcp/exceptions.py+++ b/fastmcp_slim/fastmcp/exceptions.py@@ -1,13 +1,27 @@"""Custom exceptions for FastMCP."""import logging+from typing import Any++from mcp_types import INTERNAL_ERROR, INVALID_PARAMS, ErrorDatatry:from mcp import MCPErrorexcept ImportError:class MCPError(Exception): # type: ignore[no-redef]- """Fallback used when MCP dependencies are not installed."""+ """Fallback used when MCP dependencies are not installed.++ Mirrors the real ``mcp.MCPError`` interface β the ``(code, message,+ data)`` constructor and the ``.error`` ``ErrorData`` payload β so static+ analysis of both construction and read sites (e.g. ``to_mcp_error`` and+ callers reading ``err.error.code``) is valid regardless of which branch+ is in effect.+ """++ def __init__(self, code: int, message: str, data: Any = None) -> None:+ super().__init__(message)+ self.error = ErrorData(code=code, message=message, data=data)# Catch-compatibility alias for the pre-v2 SDK name. `except McpError` must@@ -68,3 +82,33 @@ class DisabledError(Exception):class AuthorizationError(FastMCPError):"""Error when authorization check fails."""+++def to_mcp_error(exc: Exception, *, default_code: int = INTERNAL_ERROR) -> MCPError:+ """Translate a FastMCP exception into a wire-format ``MCPError``.++ Central mapping from FastMCP's public exception types to the JSON-RPC error+ codes defined by the MCP spec (imported from ``mcp_types``). Request-handler+ adapters call this instead of hand-rolling ``MCPError(code=..., ...)`` per+ call site, so the wire codes stay spec-correct and consistent across+ resources, prompts, and tools.++ ``NotFoundError`` and ``DisabledError`` map to ``INVALID_PARAMS`` (-32602):+ per SEP-2164 a request naming a component that does not exist (or is+ disabled) is an invalid-params error, which matches the SDK's own+ ``ResourceNotFoundError -> INVALID_PARAMS`` mapping in ``mcp.server.mcpserver``.+ ``ValidationError`` is also an invalid-params error. Everything else falls+ back to ``default_code`` (``INTERNAL_ERROR`` by default).++ If ``exc`` is already an ``MCPError``, it is returned unchanged so an+ explicit code chosen upstream survives translation.+ """+ if isinstance(exc, MCPError):+ return exc++ message = str(exc)+ if isinstance(exc, (NotFoundError, DisabledError)):+ return MCPError(code=INVALID_PARAMS, message=message)+ if isinstance(exc, ValidationError):+ return MCPError(code=INVALID_PARAMS, message=message)+ return MCPError(code=default_code, message=message)diff --git a/fastmcp_slim/fastmcp/server/low_level.py b/fastmcp_slim/fastmcp/server/low_level.pyindex 3e020db54..5267b1c66 100644--- a/fastmcp_slim/fastmcp/server/low_level.py+++ b/fastmcp_slim/fastmcp/server/low_level.py@@ -6,6 +6,7 @@ from contextlib import contextmanagerfrom typing import TYPE_CHECKING, Any, castimport mcp_types+from mcp.server._otel import OpenTelemetryMiddlewarefrom mcp.server.context import (CallNext,HandlerResult,@@ -26,6 +27,7 @@ from mcp.shared.exceptions import MCPErrorfrom pydantic import ValidationErrorfrom fastmcp.apps.config import UI_EXTENSION_ID+from fastmcp.server.telemetry import seam_spanfrom fastmcp.utilities.logging import get_loggerif TYPE_CHECKING:@@ -85,7 +87,11 @@ class FastMCPServerMiddleware:from fastmcp.server.dependencies import bind_request_contextfastmcp = self._ref()- with self._apply_shared_context(fastmcp), bind_request_context(ctx):+ with (+ self._apply_shared_context(fastmcp),+ bind_request_context(ctx),+ self._seam_span(fastmcp, ctx),+ ):# Only initialize requests (request_id present) go through FastMCP# middleware here; every other request already binds the context in# its own adapter, so we just pass through.@@ -94,6 +100,33 @@ class FastMCPServerMiddleware:return await self._run_initialize_mw(fastmcp, ctx, call_next)return await call_next(ctx)+ @contextmanager+ def _seam_span(+ self, fastmcp: FastMCP | None, ctx: ServerRequestContext+ ) -> Iterator[None]:+ """Open the per-request SERVER span at the middleware seam.++ The removed SDK ``OpenTelemetryMiddleware`` produced one SERVER span per+ inbound message. FastMCP re-creates that guarantee for *every* request+ method here β the last place shared by all request methods regardless of+ how their handler is registered β so a request rejected *before* the+ high-level path (FastMCP middleware, auth check, not-found mapping,+ params failure) is still traced with an error span.++ For the high-level methods (tools/resources/prompts), the deep+ ``server_span(...)`` call in ``fastmcp.server.server`` detects this seam+ span as the active span and *enriches* it in place with component+ attributes instead of opening a second span, so there is exactly one+ richly-attributed SERVER span per request. Notifications+ (``request_id is None``) are skipped β a SERVER span models an inbound+ request/response, not a fire-and-forget notification.+ """+ if fastmcp is None or ctx.request_id is None:+ yield+ return+ with seam_span(ctx.method, fastmcp.name):+ yield+@contextmanagerdef _apply_shared_context(self, fastmcp: FastMCP | None) -> Iterator[None]:"""Re-establish app-scoped SharedContext ContextVars for this request.@@ -205,8 +238,20 @@ class LowLevelServer(_Server[LifespanResultT]):tools_changed=True,)- # Route initialize through FastMCP middleware. Append so the SDK's- # seeded OpenTelemetryMiddleware stays outermost and keeps emitting spans.+ # The SDK seeds `OpenTelemetryMiddleware` into `self.middleware` so every+ # lowlevel server emits a SERVER span per message. FastMCP emits its own,+ # richer SERVER span per request (see `fastmcp.server.telemetry`), so the+ # SDK's would produce a second, duplicate SERVER span with different+ # attribute conventions for every request. Drop it β match by type rather+ # than position so we don't depend on the SDK seeding it at index 0, and+ # leave any other seeded middleware intact. FastMCP's telemetry extracts+ # inbound W3C trace context from `_meta` itself, so distributed-trace+ # propagation is unaffected.+ self.middleware = [+ mw for mw in self.middleware if not isinstance(mw, OpenTelemetryMiddleware)+ ]++ # Route initialize through FastMCP middleware.self.middleware.append(cast("ServerMiddleware[LifespanResultT]", FastMCPServerMiddleware(fastmcp)))diff --git a/fastmcp_slim/fastmcp/server/mixins/mcp_operations.py b/fastmcp_slim/fastmcp/server/mixins/mcp_operations.pyindex 0286ea1fa..74e59ae8f 100644--- a/fastmcp_slim/fastmcp/server/mixins/mcp_operations.py+++ b/fastmcp_slim/fastmcp/server/mixins/mcp_operations.py@@ -9,6 +9,7 @@ import mcp_typesfrom mcp.server.context import ServerRequestContextfrom mcp.shared.exceptions import MCPErrorfrom mcp_types import (+ INVALID_PARAMS,CallToolRequestParams,EmptyResult,GetPromptRequestParams,@@ -17,7 +18,12 @@ from mcp_types import (SetLevelRequestParams,)-from fastmcp.exceptions import DisabledError, FastMCPError, NotFoundError+from fastmcp.exceptions import (+ DisabledError,+ FastMCPError,+ NotFoundError,+ to_mcp_error,+)from fastmcp.server.dependencies import bind_request_context, extract_version_specfrom fastmcp.server.tasks.config import TaskMetafrom fastmcp.utilities.logging import get_logger@@ -46,7 +52,7 @@ def _apply_pagination(try:return paginate_sequence(items, cursor, page_size)except ValueError as e:- raise MCPError(code=-32602, message=str(e)) from e+ raise MCPError(code=INVALID_PARAMS, message=str(e)) from edef _normalize_call_tool_result(@@ -275,8 +281,8 @@ class MCPOperationsMixin:try:result = await self.read_resource(str(uri), version=version)except (DisabledError, NotFoundError) as e:- raise MCPError(- code=-32002, message=f"Resource not found: {str(uri)!r}"+ raise to_mcp_error(+ NotFoundError(f"Resource not found: {str(uri)!r}")) from eif isinstance(result, mcp_types.CreateTaskResult):@@ -308,7 +314,7 @@ class MCPOperationsMixin:try:result = await self.render_prompt(name, arguments, version=version)except (DisabledError, NotFoundError) as e:- raise MCPError(code=-32602, message=f"Unknown prompt: {name!r}") from e+ raise to_mcp_error(NotFoundError(f"Unknown prompt: {name!r}")) from eif isinstance(result, mcp_types.CreateTaskResult):return resultdiff --git a/fastmcp_slim/fastmcp/server/telemetry.py b/fastmcp_slim/fastmcp/server/telemetry.pyindex d7e62540d..eeaa0aeb7 100644--- a/fastmcp_slim/fastmcp/server/telemetry.py+++ b/fastmcp_slim/fastmcp/server/telemetry.py@@ -2,13 +2,30 @@from collections.abc import Generatorfrom contextlib import contextmanager+from contextvars import ContextVarfrom opentelemetry.context import Context-from opentelemetry.trace import Span, SpanKind, Status, StatusCode+from opentelemetry.trace import Span, SpanKind, Status, StatusCode, get_current_spanfrom fastmcp.exceptions import ToolError as _ToolErrorfrom fastmcp.telemetry import extract_trace_context, get_tracer+# Marker attribute set on the SERVER span opened at the FastMCP middleware seam+# (see `fastmcp.server.low_level.FastMCPServerMiddleware._seam_span`). The seam+# opens one span per inbound request so failures rejected *before* the+# high-level path (auth, not-found, middleware vetoes) are still traced. The+# attribute is set for observability; enrichment detection uses the ContextVar+# below (the API `Span` type does not expose readable attributes).+SEAM_SPAN_MARKER = "fastmcp.span.seam"++# Tracks the SERVER span opened at the current request's seam. When the+# high-level path reaches `server_span` and this span is still the active span,+# `server_span` enriches it with component attributes instead of opening a+# second span β restoring attribute parity on the single per-request span.+_active_seam_span: ContextVar[Span | None] = ContextVar(+ "fastmcp_active_seam_span", default=None+)+def get_auth_span_attributes() -> dict[str, str]:"""Get auth attributes for the current request, if authenticated."""@@ -51,6 +68,83 @@ def _get_parent_trace_context() -> Context | None:return None+def _build_server_span_attrs(+ method: str,+ server_name: str,+ component_type: str,+ component_key: str,+ resource_uri: str | None,+ tool_name: str | None,+ prompt_name: str | None,+) -> dict[str, str]:+ attrs: dict[str, str] = {+ # MCP semantic conventions+ "mcp.method.name": method,+ # FastMCP-specific attributes+ "fastmcp.server.name": server_name,+ "fastmcp.component.type": component_type,+ "fastmcp.component.key": component_key,+ **get_auth_span_attributes(),+ **get_session_span_attributes(),+ }+ if resource_uri is not None:+ attrs["mcp.resource.uri"] = resource_uri+ if tool_name is not None:+ attrs["gen_ai.tool.name"] = tool_name+ if prompt_name is not None:+ attrs["gen_ai.prompt.name"] = prompt_name+ return attrs+++def record_span_exception(span: Span, e: Exception) -> None:+ """Record an exception and error status on a span."""+ if span.is_recording():+ error_type = "tool_error" if isinstance(e, _ToolError) else type(e).__qualname__+ span.set_attribute("error.type", error_type)+ span.record_exception(e)+ span.set_status(Status(StatusCode.ERROR, str(e)))+++@contextmanager+def seam_span(method: str, server_name: str) -> Generator[Span, None, None]:+ """Open the per-request SERVER span at the FastMCP middleware seam.++ The span is named after the method and carries the base MCP attributes+ (`mcp.method.name`, `fastmcp.server.name`, auth/session context) so+ seam-only methods (`logging/setLevel`, `tasks/*`, `ping`, `initialize`, ...)+ are fully attributed even though they never reach the high-level path. It is+ marked with `SEAM_SPAN_MARKER` so a later `server_span` call in the+ high-level path enriches this span with component attributes instead of+ opening a second one. Exceptions raised anywhere below the seam β including+ rejections *before* the high-level path (auth, not-found, middleware vetoes)+ that would otherwise produce no SERVER span at all β are recorded here.+ """+ tracer = get_tracer()+ with tracer.start_as_current_span(+ method,+ context=_get_parent_trace_context(),+ kind=SpanKind.SERVER,+ ) as span:+ if span.is_recording():+ span.set_attribute(SEAM_SPAN_MARKER, True)+ span.set_attributes(+ {+ "mcp.method.name": method,+ "fastmcp.server.name": server_name,+ **get_auth_span_attributes(),+ **get_session_span_attributes(),+ }+ )+ token = _active_seam_span.set(span)+ try:+ yield span+ except Exception as e:+ record_span_exception(span, e)+ raise+ finally:+ _active_seam_span.reset(token)++@contextmanagerdef server_span(name: str,@@ -62,10 +156,46 @@ def server_span(tool_name: str | None = None,prompt_name: str | None = None,) -> Generator[Span, None, None]:- """Create a SERVER span with standard MCP attributes and auth context.+ """Emit or enrich a SERVER span with standard MCP attributes and auth context.++ When the current active span is the request's seam span (opened by+ `FastMCPServerMiddleware` and marked with `SEAM_SPAN_MARKER`), this sets the+ component attributes on that span and yields it *without* starting a second+ span β so failures rejected before this point and the successful high-level+ call share one richly-attributed SERVER span. Otherwise (non-seam contexts,+ e.g. in-process `mcp.call_tool()` calls that bypass the dispatcher) it opens a+ new SERVER span as before.Automatically records any exception on the span and sets error status."""+ attrs = _build_server_span_attrs(+ method,+ server_name,+ component_type,+ component_key,+ resource_uri,+ tool_name,+ prompt_name,+ )++ seam = _active_seam_span.get()+ active = get_current_span()+ if (+ seam is not None+ and seam is active+ and seam.is_recording()+ and seam.get_span_context().is_valid+ ):+ # Enrich the already-active seam span rather than opening a second one.+ seam.update_name(name)+ seam.set_attributes(attrs)+ try:+ yield seam+ except Exception as e:+ record_span_exception(seam, e)+ raise+ return+tracer = get_tracer()with tracer.start_as_current_span(name,@@ -73,33 +203,11 @@ def server_span(kind=SpanKind.SERVER,) as span:if span.is_recording():- attrs: dict[str, str] = {- # MCP semantic conventions- "mcp.method.name": method,- # FastMCP-specific attributes- "fastmcp.server.name": server_name,- "fastmcp.component.type": component_type,- "fastmcp.component.key": component_key,- **get_auth_span_attributes(),- **get_session_span_attributes(),- }- if resource_uri is not None:- attrs["mcp.resource.uri"] = resource_uri- if tool_name is not None:- attrs["gen_ai.tool.name"] = tool_name- if prompt_name is not None:- attrs["gen_ai.prompt.name"] = prompt_namespan.set_attributes(attrs)try:yield spanexcept Exception as e:- if span.is_recording():- error_type = (- "tool_error" if isinstance(e, _ToolError) else type(e).__qualname__- )- span.set_attribute("error.type", error_type)- span.record_exception(e)- span.set_status(Status(StatusCode.ERROR, str(e)))+ record_span_exception(span, e)raise@@ -128,19 +236,16 @@ def delegate_span(try:yield spanexcept Exception as e:- if span.is_recording():- error_type = (- "tool_error" if isinstance(e, _ToolError) else type(e).__qualname__- )- span.set_attribute("error.type", error_type)- span.record_exception(e)- span.set_status(Status(StatusCode.ERROR, str(e)))+ record_span_exception(span, e)raise__all__ = [+ "SEAM_SPAN_MARKER","delegate_span","get_auth_span_attributes","get_session_span_attributes",+ "record_span_exception",+ "seam_span","server_span",]diff --git a/tests/server/telemetry/test_server_tracing.py b/tests/server/telemetry/test_server_tracing.pyindex 2b98ae6cc..c04f49fd6 100644--- a/tests/server/telemetry/test_server_tracing.py+++ b/tests/server/telemetry/test_server_tracing.py@@ -8,9 +8,10 @@ import pytestfrom opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporterfrom opentelemetry.trace import SpanKind, StatusCode-from fastmcp import FastMCP+from fastmcp import Client, FastMCPfrom fastmcp.exceptions import NotFoundError, ToolErrorfrom fastmcp.server.auth import AccessToken+from fastmcp.server.middleware.middleware import CallNext, Middleware, MiddlewareContextclass TestToolTracing:@@ -350,3 +351,227 @@ class TestAuthAttributesOnSpans:assert span.attributes["enduser.id"] == "client-no-scopes"# Scope attribute should not be present when scopes list is emptyassert "enduser.scope" not in span.attributes+++class TestSingleServerSpan:+ """Full-dispatch tests guarding against duplicate SERVER spans.++ The SDK seeds its own `OpenTelemetryMiddleware` into every lowlevel server,+ which would emit a second SERVER span per request alongside FastMCP's. These+ tests exercise the real request path (through a `Client`) so a regression+ that re-enables the SDK middleware would surface as an extra SERVER span.+ Note the in-process `mcp.call_tool` tests above bypass the dispatcher and so+ cannot catch this.+ """++ async def test_tool_call_emits_single_server_span(+ self, trace_exporter: InMemorySpanExporter+ ):+ mcp = FastMCP("test-server")++ @mcp.tool()+ def greet(name: str) -> str:+ return f"Hello, {name}!"++ async with Client(mcp) as client:+ await client.call_tool("greet", {"name": "World"})++ spans = trace_exporter.get_finished_spans()+ # Exactly one SERVER span for the tools/call request. Match by method name+ # (not just the "tools/call greet" name) so a seam-level span accidentally+ # opened for this high-level method β which would be named "tools/call" β+ # is also counted and would trip the assertion.+ tool_call_server_spans = [+ s+ for s in spans+ if s.kind == SpanKind.SERVER+ and s.attributes is not None+ and s.attributes.get("mcp.method.name") == "tools/call"+ ]+ assert len(tool_call_server_spans) == 1+ span = tool_call_server_spans[0]+ assert span.name == "tools/call greet"+ # The single span carries the rich component attributes that the+ # high-level path enriches the seam span with (attribute parity: the+ # enrichment must not lose the component context by opening a second+ # span or by leaving the seam span bare).+ assert span.attributes is not None+ assert span.attributes["fastmcp.component.key"] == "tool:greet@"+ assert span.attributes["gen_ai.tool.name"] == "greet"+ assert span.attributes["fastmcp.component.type"] == "tool"++ async def test_server_span_shares_client_trace(+ self, trace_exporter: InMemorySpanExporter+ ):+ """FastMCP extracts inbound W3C trace context from `_meta`, so the single+ SERVER span must still join the client's distributed trace."""+ mcp = FastMCP("test-server")++ @mcp.tool()+ def greet(name: str) -> str:+ return f"Hello, {name}!"++ async with Client(mcp) as client:+ await client.call_tool("greet", {"name": "World"})++ spans = trace_exporter.get_finished_spans()+ server_span = next(+ s+ for s in spans+ if s.kind == SpanKind.SERVER and s.name == "tools/call greet"+ )+ client_span = next(+ s+ for s in spans+ if s.kind == SpanKind.CLIENT and s.name == "MCP send tools/call greet"+ )+ assert server_span.context is not None+ assert client_span.context is not None+ assert server_span.context.trace_id == client_span.context.trace_id+ assert server_span.parent is not None+++class TestSeamServerSpan:+ """SERVER spans for methods outside the high-level tool/resource/prompt path.++ FastMCP's rich SERVER spans are created deep in the high-level path, so+ methods like `logging/setLevel`, `tasks/*`, `ping`, and `initialize` β which+ never reach that code β would have no span at all once the SDK's+ `OpenTelemetryMiddleware` is removed. The FastMCP middleware seam+ (`FastMCPServerMiddleware`) emits a span for exactly those methods, so every+ request method carries a SERVER span again.+ """++ async def test_set_logging_level_emits_seam_span(+ self, trace_exporter: InMemorySpanExporter+ ):+ mcp = FastMCP("test-server")++ async with Client(mcp) as client:+ await client.set_logging_level("info")++ spans = trace_exporter.get_finished_spans()+ seam_spans = [+ s+ for s in spans+ if s.kind == SpanKind.SERVER and s.name == "logging/setLevel"+ ]+ assert len(seam_spans) == 1+ span = seam_spans[0]+ assert span.attributes is not None+ assert span.attributes["mcp.method.name"] == "logging/setLevel"+ assert span.attributes["fastmcp.server.name"] == "test-server"++ async def test_seam_method_emits_single_server_span(+ self, trace_exporter: InMemorySpanExporter+ ):+ """A seam-spanned method must produce exactly one SERVER span, not two."""+ mcp = FastMCP("test-server")++ async with Client(mcp) as client:+ await client.set_logging_level("info")++ spans = trace_exporter.get_finished_spans()+ set_level_server_spans = [+ s+ for s in spans+ if s.kind == SpanKind.SERVER+ and s.attributes is not None+ and s.attributes.get("mcp.method.name") == "logging/setLevel"+ ]+ assert len(set_level_server_spans) == 1+++class TestFailurePathServerSpan:+ """A tools/call rejected before the high-level handler must still be traced.++ The rich SERVER span for tools/call is created deep in the high-level path,+ after FastMCP middleware runs. A request rejected *before* that point (a+ raising middleware, a not-found tool) never reaches it, so without the seam+ span such failures would produce no SERVER span at all β the failure-path+ observability regression this guards against. The seam span opened by+ `FastMCPServerMiddleware` wraps the whole request, so every tools/call+ carries a SERVER span with `mcp.method.name=tools/call`, and an exception+ that propagates past the handler marks that span's status as an error.+ """++ async def test_middleware_error_before_handler_emits_error_span(+ self, trace_exporter: InMemorySpanExporter+ ):+ """An unexpected error raised in FastMCP middleware, before the+ high-level path, propagates to the seam span, which records it as an+ error β where previously this method produced no SERVER span at all."""++ class RaisingMiddleware(Middleware):+ async def on_call_tool(+ self,+ context: MiddlewareContext,+ call_next: CallNext,+ ):+ raise RuntimeError("rejected before handler")++ mcp = FastMCP("test-server", middleware=[RaisingMiddleware()])++ @mcp.tool()+ def greet(name: str) -> str:+ return f"Hello, {name}!"++ async with Client(mcp) as client:+ with pytest.raises(Exception):+ await client.call_tool("greet", {"name": "World"})++ spans = trace_exporter.get_finished_spans()+ tool_call_server_spans = [+ s+ for s in spans+ if s.kind == SpanKind.SERVER+ and s.attributes is not None+ and s.attributes.get("mcp.method.name") == "tools/call"+ ]+ assert len(tool_call_server_spans) == 1+ span = tool_call_server_spans[0]+ assert span.status.status_code == StatusCode.ERROR+ assert span.attributes is not None+ assert span.attributes["mcp.method.name"] == "tools/call"+ assert span.attributes["error.type"] == "RuntimeError"+ assert len(span.events) > 0 # exception recorded++ async def test_tool_visible_rejection_before_handler_still_spans(+ self, trace_exporter: InMemorySpanExporter+ ):+ """A tool-visible error raised in middleware is returned as an error+ result (correct MCP semantics, so the span status is unset), but the+ seam span still guarantees exactly one SERVER span for the tools/call β+ the request is no longer invisible to tracing."""++ class RejectingMiddleware(Middleware):+ async def on_call_tool(+ self,+ context: MiddlewareContext,+ call_next: CallNext,+ ):+ raise ToolError("rejected before handler")++ mcp = FastMCP("test-server", middleware=[RejectingMiddleware()])++ @mcp.tool()+ def greet(name: str) -> str:+ return f"Hello, {name}!"++ async with Client(mcp) as client:+ with pytest.raises(ToolError):+ await client.call_tool("greet", {"name": "World"})++ spans = trace_exporter.get_finished_spans()+ tool_call_server_spans = [+ s+ for s in spans+ if s.kind == SpanKind.SERVER+ and s.attributes is not None+ and s.attributes.get("mcp.method.name") == "tools/call"+ ]+ assert len(tool_call_server_spans) == 1+ assert (+ tool_call_server_spans[0].attributes is not None+ and tool_call_server_spans[0].attributes["mcp.method.name"] == "tools/call"+ )diff --git a/tests/test_exceptions.py b/tests/test_exceptions.pynew file mode 100644index 000000000..d85ea0322--- /dev/null+++ b/tests/test_exceptions.py@@ -0,0 +1,82 @@+"""Tests for FastMCP's exception-to-wire-error translation."""++from __future__ import annotations++import pytest+from mcp import MCPError+from mcp_types import INTERNAL_ERROR, INVALID_PARAMS++from fastmcp import Client, FastMCP+from fastmcp.exceptions import (+ DisabledError,+ NotFoundError,+ PromptError,+ ResourceError,+ ToolError,+ ValidationError,+ to_mcp_error,+)+++class TestToMcpError:+ @pytest.mark.parametrize(+ "exc",+ [NotFoundError("missing"), DisabledError("off"), ValidationError("bad")],+ )+ def test_invalid_params_mapping(self, exc: Exception):+ """Not-found, disabled, and validation errors map to INVALID_PARAMS.++ SEP-2164 defines a request naming a nonexistent (or disabled) component+ as an invalid-params error, matching the SDK's own mcpserver mapping.+ """+ result = to_mcp_error(exc)+ assert isinstance(result, MCPError)+ assert result.error.code == INVALID_PARAMS+ assert result.error.message == str(exc)++ @pytest.mark.parametrize(+ "exc",+ [ResourceError("boom"), PromptError("boom"), ToolError("boom")],+ )+ def test_default_code_for_unmapped_errors(self, exc: Exception):+ """Operation errors without a dedicated mapping use the default code."""+ assert to_mcp_error(exc).error.code == INTERNAL_ERROR++ def test_custom_default_code(self):+ assert (+ to_mcp_error(ResourceError("x"), default_code=-32000).error.code == -32000+ )++ def test_existing_mcp_error_passes_through(self):+ """An MCPError chosen upstream survives translation unchanged."""+ existing = MCPError(code=-32000, message="explicit")+ assert to_mcp_error(existing) is existing+++class TestWireErrorCodes:+ """The core request-handler adapters must emit spec-correct wire codes."""++ async def test_resource_not_found_uses_invalid_params(self):+ """Resource-not-found is INVALID_PARAMS (-32602), not -32002.++ SEP-2164 corrected this: the SDK's mcpserver maps ResourceNotFoundError+ to INVALID_PARAMS. FastMCP previously deviated with -32002.+ """+ mcp = FastMCP("test-server")++ async with Client(mcp) as client:+ with pytest.raises(MCPError) as exc_info:+ await client.read_resource_mcp("config://missing")++ assert exc_info.value.error.code == INVALID_PARAMS+ assert "Resource not found" in exc_info.value.error.message++ async def test_prompt_not_found_uses_invalid_params(self):+ mcp = FastMCP("test-server")++ async with Client(mcp) as client:+ with pytest.raises(MCPError) as exc_info:+ await client.get_prompt("missing", {})++ assert exc_info.value.error.code == INVALID_PARAMS+ assert "Unknown prompt" in exc_info.value.error.message