feat: Add telemetry interop mode for FastMCP

[strawgate]

When another instrumentation layer (e.g. an MCP-aware OTEL library or a service mesh) already owns the MCP span hierarchy, FastMCP's native spans become duplicates. This PR adds a minimal interop mode that lets users suppress FastMCP's own spans while keeping trace context propagation through _meta fully functional.

import fastmcp

# Global: suppress all FastMCP spans
fastmcp.settings.telemetry_mode = "propagation_only"

# Or per-scope: suppress only within a block
from fastmcp.telemetry import suppress_fastmcp_telemetry

with suppress_fastmcp_telemetry():
    result = await client.call_tool("search", {"query": "otel"})

The setting (FASTMCP_TELEMETRY_MODE) controls all three span helpers (server_span, client_span, delegate_span). In propagation_only mode, incoming trace context from _meta is still extracted and attached so downstream user spans inherit the correct parent—only FastMCP's own MCP operation spans are skipped.

This follows the universal pattern seen in FastAPI, Django, Flask, Sentry, and gRPC instrumentation libraries: extract→attach→skip span→detach.

[marvin-context-protocol]

tl;dr: A pre-existing test, test_refresh_expires_in_zero_issues_refresh_token, is now failing because the PR's change to proxy.py sets refresh_expires_in = None for the raw_value == 0 branch, which causes downstream gating logic to silently skip issuing the refresh token. Fix by using the fallback expiry instead of None in that branch.

---

(Edited to reflect latest CI failure — this replaces the earlier ruff format report.)

Root Cause: In src/fastmcp/server/auth/oauth_proxy/proxy.py, the new raw_value == 0 branch sets refresh_expires_in = None (to represent "never expires"). But two downstream checks gate refresh token issuance and storage on refresh_expires_in being truthy:

# line 1128 — None is falsy → fastmcp_refresh_token stays None
if refresh_jti and refresh_expires_in:
    fastmcp_refresh_token = self.jwt_issuer.issue_refresh_token(...)

# line 1159 — fastmcp_refresh_token is None → no metadata stored
if fastmcp_refresh_token and refresh_expires_in:
    await self._refresh_token_store.put(...)

result.refresh_token ends up None, failing the assertion at test_tokens.py:874.

Fix: In the raw_value == 0 branch of the new code, use the configured fallback instead of None. This matches the test's own docstring: "refresh_expires_in=0 should fall back to the configured default."

# Before (PR's new code — broken):
if raw_value == 0:
    refresh_expires_in = None
    refresh_token_expires_at = None

# After (correct):
if raw_value == 0:
    refresh_expires_in = self._fallback_refresh_token_expiry_seconds
    refresh_token_expires_at = time.time() + refresh_expires_in

Log excerpt

FAILED tests/server/auth/oauth_proxy/test_tokens.py::TestUpstreamTokenStorageTTL::test_refresh_expires_in_zero_issues_refresh_token
AssertionError: assert None is not None
 +  where None = OAuthToken(access_token='***', token_type='Bearer', expires_in=3600, scope='read write', refresh_token=None).refresh_token

Reproduced across all failing matrix jobs (Python 3.10 / 3.13 on ubuntu and windows, plus lowest-direct-deps).

Related files

• src/fastmcp/server/auth/oauth_proxy/proxy.py — lines 1064–1085 (new refresh_expires_in=0 branch), 1128, 1159
• tests/server/auth/oauth_proxy/test_tokens.py — TestUpstreamTokenStorageTTL::test_refresh_expires_in_zero_issues_refresh_token (line 825)

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3d90859a4d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".