Skip to content
Merged
Show file tree
Hide file tree
Changes from 2 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
38 changes: 8 additions & 30 deletions docs/advanced/middleware.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,33 +79,12 @@ In increasing order of how much you should hesitate:
an elicitation) while handling `initialize` therefore **deadlocks the connection**: the
response you are waiting for can never be read. Fire-and-forget notifications are fine.

## `OpenTelemetryMiddleware`

The SDK ships one middleware: `OpenTelemetryMiddleware`. Construct it and append it
(`server.middleware.append(OpenTelemetryMiddleware())`), exactly the line you already wrote
for `log_timing`.

Every inbound message becomes a `SERVER` span named after the method and its target, so a
`tools/call` for `search_books` is the span `tools/call search_books`.

* Every span carries `mcp.method.name` and `mcp.protocol.version`; a request's span also
carries its JSON-RPC request id (a notification has none).
* A `tools/call` span gets OpenTelemetry's GenAI semantic conventions,
`gen_ai.operation.name` (`"execute_tool"`) and `gen_ai.tool.name`, so a tracing UI groups
your tool calls the way it groups any other agent's. A `prompts/get` span gets
`gen_ai.prompt.name`. The list methods carry no `gen_ai.*` keys.
* A handler that raises sets the span's status to error. So does a tool result with
`is_error=True`.

!!! tip
The SDK depends only on `opentelemetry-api`. With no exporter installed those spans are
no-ops, so appending this middleware costs you nothing. Install `opentelemetry-sdk` plus an
exporter and everything lights up, with no server change.

The import is the catch. The class lives at `from mcp.server._otel import OpenTelemetryMiddleware`
today, and the leading underscore is not an accident: it is the same provisional flag this whole
page opened with. The SDK has not given it a public spelling yet, so the import path is the one
line here you should expect to change.
## The one middleware that ships on by default

The SDK ships exactly one middleware, and it is already on your server's list: the one that
emits an OpenTelemetry span for every message. You don't append it, and most of the time you
don't think about it. It is a no-op until you install an exporter, and it has its own page:
**OpenTelemetry**.

!!! info
If you have written ASGI middleware, you already know this shape. Starlette's
Expand All @@ -121,9 +100,8 @@ line here you should expect to change.
unknown methods) and runs outermost-first.
* `ctx.request_id is None` is how you tell a notification from a request.
* Raise instead of calling `call_next` to refuse one message; the connection survives.
* `OpenTelemetryMiddleware` turns each message into a span (with GenAI attributes on tool
calls and prompt gets) for the price of one `append`, and costs nothing until you install
an exporter.
* The SDK's own OpenTelemetry tracing is a middleware too, already on the list. See
**OpenTelemetry**.
* The whole surface is provisional. Observe with it; don't build on it.

That is everything that wraps a request. **Authorization** is what decides whether the request
Comment on lines 105 to 107

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 The closing hand-off on this page still points to Authorization, but this PR inserts the new OpenTelemetry page between Middleware and Authorization in the mkdocs nav (and opentelemetry.md itself hands off to Authorization). Consider updating the closing sentence to hand off to OpenTelemetry so it matches the new nav order.

Extended reasoning...

What the issue is

The docs in this repo follow a consistent convention: each page closes with a hand-off sentence pointing to the next page in the mkdocs nav (e.g. logging.md ends by pointing to Testing, and the new opentelemetry.md ends with "Next, the thing that decides whether a request runs at all: Authorization."). This PR changes the nav in mkdocs.yml from Middleware -> Authorization to Middleware -> OpenTelemetry -> Authorization, but docs/advanced/middleware.md still closes with:

That is everything that wraps a request. Authorization is what decides whether the request gets to run at all.

Why this is inconsistent after this PR

Step-by-step:

  1. mkdocs.yml in this PR adds OpenTelemetry: advanced/opentelemetry.md directly between Middleware and Authorization in the Advanced nav section.
  2. The new docs/advanced/opentelemetry.md ends with its own hand-off to Authorization, following the established next-page convention.
  3. middleware.md (edited by this same PR) still ends by handing off to Authorization, so the page now skips over the page that immediately follows it in the nav, and two consecutive pages both hand off to Authorization.
  4. The skipped page is the very one this PR's other edits to middleware.md direct readers to twice ("See OpenTelemetry" in the new section and in the recap), so a reader following the closing pointer jumps past content the page itself just told them to read.

Why nothing else catches it

The closing sentence is prose, so mkdocs' strict: true build and the link/anchor validation in mkdocs.yml cannot flag it — the sentence is not a hyperlink, just bolded text naming the next page. It is also not factually wrong (Authorization does decide whether a request runs), so only a human reading the page flow notices the skip.

Impact

Purely a documentation-flow polish issue: readers who follow the end-of-page hand-offs in order will skip the new OpenTelemetry page, even though the body of middleware.md references it. No functional or build impact.

How to fix

Reword the closing sentence of docs/advanced/middleware.md to hand off to OpenTelemetry instead — for example: "That is everything that wraps a request. The one middleware the SDK ships for you has its own page: OpenTelemetry." — leaving opentelemetry.md to carry the existing hand-off to Authorization.

Expand Down
107 changes: 107 additions & 0 deletions docs/advanced/opentelemetry.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
# OpenTelemetry

Your server is already traced. You don't have to add anything.

Every server you create emits an [OpenTelemetry](https://opentelemetry.io/) span for every
message it handles. You didn't write that, and you don't import it. It is there the moment you
call `MCPServer(...)`.

```python title="server.py"
--8<-- "docs_src/opentelemetry/tutorial001.py"
```

That is a complete, traced server. Call `search_books` and a span is created for it. The same is
true for the low-level `Server`: the tracing lives on both.

## What you get

Every inbound message becomes a `SERVER` span named after the method and its target. So a
`tools/call` for `search_books` is the span `tools/call search_books`, and a bare `tools/list`
is just `tools/list`.

Each span carries a few attributes:

* `mcp.method.name` and `mcp.protocol.version`, on every span.
* `jsonrpc.request.id`, on a request (a notification has none).
* A handler that raises sets the span status to error. So does a tool result with `is_error=True`.

And because tracing a tool call is such a common thing to want, `tools/call` spans speak
OpenTelemetry's [GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/):

* `gen_ai.operation.name`, set to `"execute_tool"`.
* `gen_ai.tool.name`, set to the tool being called.

A `prompts/get` span gets `gen_ai.prompt.name` in the same spirit. The list methods carry no
`gen_ai.*` keys, because there is nothing to name.

!!! tip
Those GenAI attributes are the reason a tracing UI groups your tool calls the way it groups
any other agent's. You get that grouping for free, with no extra code.

## It costs nothing until you want it

Here is the part that makes "on by default" a comfortable default.

The SDK depends only on `opentelemetry-api`, the lightweight half of OpenTelemetry. With no SDK
and no exporter installed, creating a span is a no-op. So the spans your server is emitting right
now cost you almost nothing, and nobody is collecting them.

The day you want to *see* them, you install the other half and point it somewhere:

```console
uv add opentelemetry-sdk opentelemetry-exporter-otlp
```

Configure an exporter the usual OpenTelemetry way, and every span the SDK has been quietly
creating lights up. Your server code does not change. Not one line.

!!! info
[Pydantic Logfire](https://logfire.pydantic.dev/) is one such backend, and it does the
configuration for you: `pip install logfire`, `logfire.configure()`, and your MCP spans show
up in the live view. It is built on OpenTelemetry, so anything below applies to it too.

## Traces that cross the wire

A trace is most useful when it follows a request from the client into the server, in one
connected picture.

When the client and the server both run the SDK, that connection is automatic. The client injects
the [W3C trace context](https://www.w3.org/TR/trace-context/) into the request, and the server
reads it back out, so the server span nests under the client span in the same trace. This is
[SEP-414](https://github.com/modelcontextprotocol/modelcontextprotocol), and you get it without
asking.

If the inbound message carries no trace context, for example a request from a client that is not
the SDK, the server span simply parents to whatever span is already current on the server, rather
than starting a brand-new orphan trace.

## Turning it off

Tracing is a middleware, the first one on your server's list. If you really want a server that
emits no spans, take it off:

```python
from mcp.server._otel import OpenTelemetryMiddleware

mcp._lowlevel_server.middleware[:] = [
m for m in mcp._lowlevel_server.middleware if not isinstance(m, OpenTelemetryMiddleware)
]
```

!!! warning
That import has a leading underscore, and that is on purpose. The class is provisional, the
same way [`Server.middleware`](middleware.md) is provisional, so the import path is something
you should expect to change. You almost never need this: with no exporter installed the spans
are free, so the usual answer is to leave them on and not install an exporter.

## Recap

* Every `MCPServer` and every low-level `Server` emits one `SERVER` span per inbound message, out
of the box. You write nothing.
* Spans carry `mcp.method.name` and `mcp.protocol.version`; `tools/call` and `prompts/get` also
carry GenAI attributes so your tool calls group like any other agent's.
* It costs nothing until you install an OpenTelemetry SDK and an exporter, and then it lights up
with no change to your server.
* Client-to-server trace context propagates automatically when both sides run the SDK.

Next, the thing that decides whether a request runs at all: **Authorization**.
4 changes: 2 additions & 2 deletions docs/tutorial/logging.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,8 +64,8 @@ went to standard error: the terminal, not the wire.

!!! info
If what you actually want is *tracing* (every request, how long it took, whether it failed), you
don't want log lines, you want spans. The SDK ships an `OpenTelemetryMiddleware` for exactly that.
See **Middleware**.
don't want log lines, you want spans. Your server already emits them: the SDK traces every
message with OpenTelemetry out of the box. See **OpenTelemetry**.

## Recap

Expand Down
Empty file.
9 changes: 9 additions & 0 deletions docs_src/opentelemetry/tutorial001.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
from mcp.server import MCPServer

mcp = MCPServer("Bookshop")


@mcp.tool()
def search_books(query: str) -> str:
"""Search the catalog by title or author."""
return f"Found 3 books matching {query!r}."
1 change: 1 addition & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ nav:
- The low-level Server: advanced/low-level-server.md
- Pagination: advanced/pagination.md
- Middleware: advanced/middleware.md
- OpenTelemetry: advanced/opentelemetry.md
- Authorization: advanced/authorization.md
- OAuth clients: advanced/oauth-clients.md
- Session groups: advanced/session-groups.md
Expand Down
2 changes: 1 addition & 1 deletion src/mcp/server/context.py
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ async def log(self, level: LoggingLevel, data: Any, logger: str | None = None, *
class ServerMiddleware(Protocol[_MwLifespanT]):
"""Context-tier middleware: `(ctx, call_next) -> result`.

Runs at the top of `ServerRunner._on_request` / `_on_notify` after `ctx`
Runs at the top of `ServerRunner.on_request` / `_on_notify` after `ctx`
is built but before any validation, lookup, or handshake. Wraps every
inbound request and notification: `initialize`, the pre-init gate,
`METHOD_NOT_FOUND`, params validation, the handler call, and
Expand Down
8 changes: 6 additions & 2 deletions src/mcp/server/lowlevel/server.py
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,7 @@ async def main():
from starlette.routing import Mount, Route
from typing_extensions import TypeVar

from mcp.server._otel import OpenTelemetryMiddleware
from mcp.server.auth.middleware.auth_context import AuthContextMiddleware
from mcp.server.auth.middleware.bearer_auth import BearerAuthBackend, RequireAuthMiddleware
from mcp.server.auth.provider import OAuthAuthorizationServerProvider, TokenVerifier
Expand Down Expand Up @@ -230,11 +231,14 @@ def __init__(
self._session_manager: StreamableHTTPSessionManager | None = None
# Context-tier middleware: wraps every inbound request (including
# `initialize`, lookup, validation, handler) with
# `(ctx, call_next)`. Applied in `ServerRunner._on_request`.
# `(ctx, call_next)`. Applied in `ServerRunner.on_request`.
# `OpenTelemetryMiddleware` ships on by default so every server emits a
# SERVER span per message; it is a no-op until an OTel exporter is
# installed. Drop it from this list to opt out.
# TODO(L54): provisional - signature and semantics change with the
# Context/middleware rework (covariant `Context[L]`, outbound seam) before
# v2 final.
self.middleware: list[ServerMiddleware[LifespanResultT]] = []
self.middleware: list[ServerMiddleware[LifespanResultT]] = [OpenTelemetryMiddleware()]
logger.debug("Initializing server %r", name)

_spec_requests: list[tuple[str, type[BaseModel], RequestHandler[LifespanResultT, Any] | None]] = [
Expand Down
80 changes: 6 additions & 74 deletions src/mcp/server/runner.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,9 @@
from __future__ import annotations

import logging
from collections.abc import Awaitable, Mapping, Sequence
from collections.abc import Awaitable, Mapping
from dataclasses import KW_ONLY, dataclass
from functools import cached_property, partial, reduce
from functools import cached_property, partial
from typing import TYPE_CHECKING, Any, Generic, cast

import anyio
Expand All @@ -37,17 +37,15 @@
)
from mcp_types import methods as _methods
from mcp_types.version import HANDSHAKE_PROTOCOL_VERSIONS, LATEST_HANDSHAKE_VERSION, LATEST_MODERN_VERSION
from opentelemetry.trace import SpanKind, StatusCode
from pydantic import BaseModel, ValidationError
from typing_extensions import TypeVar

from mcp.server.connection import Connection
from mcp.server.context import CallNext, HandlerResult, ServerMiddleware, ServerRequestContext
from mcp.server.models import InitializationOptions
from mcp.server.session import ServerSession
from mcp.shared._otel import extract_trace_context, otel_span
from mcp.shared._stream_protocols import ReadStream, WriteStream
from mcp.shared.dispatcher import DispatchContext, Dispatcher, DispatchMiddleware, OnNotify, OnRequest
from mcp.shared.dispatcher import DispatchContext, Dispatcher, OnNotify, OnRequest
from mcp.shared.exceptions import MCPError
from mcp.shared.jsonrpc_dispatcher import JSONRPCDispatcher
from mcp.shared.message import ServerMessageMetadata, SessionMessage
Expand All @@ -62,7 +60,6 @@
"ServerRunner",
"aclose_shielded",
"modern_on_request",
"otel_middleware",
"serve_connection",
"serve_loop",
"serve_one",
Expand Down Expand Up @@ -91,58 +88,6 @@ def _extract_meta(params: Mapping[str, Any] | None) -> RequestParamsMeta | None:
return None


def otel_middleware(call_next: OnRequest) -> OnRequest:
"""Dispatch-tier middleware that wraps each request in an OpenTelemetry span.

Mirrors the span shape of the existing `Server._handle_request`: span name
`"MCP handle <method> [<target>]"`, `mcp.method.name` attribute, W3C
trace context extracted from `params._meta` (SEP-414), and an ERROR
status if the handler raises.
"""

async def wrapped(
dctx: DispatchContext[TransportContext], method: str, params: Mapping[str, Any] | None
) -> dict[str, Any]:
target: str | None
match params:
case {"name": str() as target}:
pass
case _:
target = None
parent: Any | None
match params:
case {"_meta": {**meta}}:
parent = extract_trace_context(meta)
case _:
parent = None
span_name = f"MCP handle {method}{f' {target}' if target else ''}"
# `otel_middleware` wraps `on_request` only, so `request_id` is always set.
attributes = {"mcp.method.name": method, "jsonrpc.request.id": str(dctx.request_id)}
with otel_span(
span_name,
kind=SpanKind.SERVER,
attributes=attributes,
context=parent,
record_exception=False,
set_status_on_exception=False,
) as span:
try:
return await call_next(dctx, method, params)
except MCPError as e:
span.set_status(StatusCode.ERROR, e.error.message)
raise
except ValidationError:
# Mirror the sanitized wire response; pydantic messages carry client input.
span.set_status(StatusCode.ERROR, "Invalid request parameters")
raise
except Exception as e:
span.record_exception(e)
span.set_status(StatusCode.ERROR, str(e))
raise

return wrapped


def _dump_result(result: Any) -> dict[str, Any]:
if result is None:
return {}
Expand Down Expand Up @@ -196,25 +141,12 @@ class ServerRunner(Generic[LifespanT]):
_: KW_ONLY
init_options: InitializationOptions | None = None
"""`InitializeResult` payload. Defaults to `server.create_initialization_options()`."""
dispatch_middleware: Sequence[DispatchMiddleware] = (otel_middleware,)

@cached_property
def on_request(self) -> OnRequest:
"""`_on_request` wrapped in `dispatch_middleware`, outermost-first.

Dispatch-tier middleware sees raw `(dctx, method, params) -> dict` and
wraps everything - initialize, METHOD_NOT_FOUND, validation failures
included.
"""
return reduce(
lambda handler, middleware: middleware(handler), reversed(self.dispatch_middleware), self._on_request
)

@cached_property
def on_notify(self) -> OnNotify:
return self._on_notify

async def _on_request(
async def on_request(
self,
dctx: DispatchContext[TransportContext],
method: str,
Expand Down Expand Up @@ -343,7 +275,7 @@ async def _inner(ctx: ServerRequestContext[LifespanT, Any]) -> None:
def _compose_server_middleware(self, inner: CallNext) -> CallNext:
"""Wrap `inner` in `Server.middleware`, outermost-first.

Shared by `_on_request` and `_on_notify` so the same middleware chain
Shared by `on_request` and `_on_notify` so the same middleware chain
observes every inbound message. The composed callable takes the `ctx`
at call time, so a middleware can rewrite it for the rest of the chain.
"""
Expand Down Expand Up @@ -396,7 +328,7 @@ def _negotiate_initialize(params: Mapping[str, Any] | None) -> tuple[InitializeR
return init, negotiated

def _handle_initialize(self, params: Mapping[str, Any] | None) -> InitializeResult:
"""Build the `initialize` result; state commits later in `_on_request`."""
"""Build the `initialize` result; state commits later in `on_request`."""
_, negotiated = self._negotiate_initialize(params)
opts = self.init_options if self.init_options is not None else self.server.create_initialization_options()
return InitializeResult(
Expand Down
4 changes: 0 additions & 4 deletions src/mcp/shared/dispatcher.py
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,6 @@
__all__ = [
"CallOptions",
"DispatchContext",
"DispatchMiddleware",
"Dispatcher",
"OnNotify",
"OnRequest",
Expand Down Expand Up @@ -185,9 +184,6 @@ async def progress(self, progress: float, total: float | None = None, message: s
OnNotify = Callable[[DispatchContext[TransportContext], str, Mapping[str, Any] | None], Awaitable[None]]
"""Handler for inbound notifications: `(ctx, method, params)`."""

DispatchMiddleware = Callable[[OnRequest], OnRequest]
"""Wraps an `OnRequest` to produce another `OnRequest`. Applied outermost-first."""


class Dispatcher(Outbound, Protocol[TransportT_co]):
"""A duplex request/notification channel with call-return semantics.
Expand Down
Loading
Loading