prefecthq-fastmcp-3827-3889

lrwxrwxrwx 1 root root      9 Nov  5 17:24 AGENTS.md -> CLAUDE.md
-rw-r--r-- 1 root root  10467 Nov  5 17:24 CLAUDE.md
-rw-r--r-- 1 root root   5218 Nov  5 17:24 CODE_OF_CONDUCT.md
-rw-r--r-- 1 root root   5633 Nov  5 17:24 CONTRIBUTING.md
-rw-r--r-- 1 root root  11356 Nov  5 17:24 LICENSE
-rw-r--r-- 
…[1072 chars omitted]…

./examples/tags_example.py
./examples/task_elicitation.py
./examples/text_me.py
./examples/tool_result_echo.py
./logo.py
./scripts/auto_close_duplicates.py
./scripts/auto_close_needs_mre.py
./scripts/benchmark_imports.py
./tests/conftest.py
./tests/test_apps.py
./tests/test_apps_prefab.py
./tests/test_fastmcp_app.py
./tests/test_json_schema_generation.py
./tests/test_mcp_config.py
./tests/__init__.py

src/fastmcp/cli/auth.py
src/fastmcp/cli/cimd.py
src/fastmcp/cli/cli.py
src/fastmcp/cli/client.py
src/fastmcp/cli/discovery.py
src/fastmcp/cli/generate.py
src/fastmcp/cli/install/__init__.py
src/fastmcp/cli/install/claude_code.py
src/fastmcp/cli/install/claude_desktop.py
src/fastmcp/cli/install/cursor.py
src/fastmcp/cli/install/gemini_cli.py
src/fastmcp/cli/install/goose.py
src/fastmcp/cli/install/mcp_json.py
src/fastmcp/cli/install/shared.py
src/fastmcp/cli/install/stdio.py
src/fastmcp/cli/run.py
src/fastmcp/cli/tasks.py
src/fastmcp/client/__init__.py
src/fas
…[8629 chars omitted]…
erver/providers/__init__.py
tests/server/providers/local_provider_tools/__init__.py
tests/server/providers/local_provider_tools/test_context.py
tests/server/providers/local_provider_tools/test_decorator.py
tests/server/providers/local_provider_tools/test_enabled.py
tests/server/providers/local_provider_tools/test_local_provider_tools.py
tests/server/providers/local_provider_tools/test_output_schema.py

src/fastmcp/server/auth/oauth_proxy/models.py
src/fastmcp/server/auth/oauth_proxy/proxy.py
src/fastmcp/server/auth/oauth_proxy/ui.py
src/fastmcp/server/auth/oidc_proxy.py
src/fastmcp/server/auth/providers/__init__.py
src/fastmcp/server/auth/providers/auth0.py
src/fastmcp/server/auth/providers/aws.py
src/fastmcp/server/auth/providers/azure.py
src/fastmcp/server/auth/providers/clerk.py
src/fastmcp/server/auth/providers/debug.py
src/fastmcp/server/auth/p
…[4003 chars omitted]…
filter.py
src/fastmcp/server/transforms/visibility.py
---MOUNT TESTS---
__init__.py
test_advanced.py
test_filtering.py
test_mount.py
test_prompts.py
test_proxy.py
test_resources.py
---TELEMETRY TESTS---
tests/client/telemetry
tests/client/telemetry/test_client_tracing.py
tests/server/telemetry
tests/server/telemetry/test_provider_tracing.py
tests/server/telemetry/test_server_tracing.py
tests/telemetry

    name: str,
    method: str,
    component_key: str,
    session_id: str | None = None,
    resource_uri: str | None = None,
) -> Generator[Span, None, None]:
    """Create a CLIENT span with standard MCP attributes.

    Automatically records any exception on the span and sets error status.
    """
    tracer = get_tracer()
    with tracer.start_as_current_span(name, kind=SpanKind.CLIENT) as span:
        attrs: dict[str, str] = {
            # RPC semantic conventions
            "rpc.system": "mcp",
            "rpc.method": method,
            # MCP semantic conventions
            "mcp.method.name": method,
            # F
…[73 chars omitted]…
_key,
        }
        if session_id:
            attrs["mcp.session.id"] = session_id
        if resource_uri:
            attrs["mcp.resource.uri"] = resource_uri
        span.set_attributes(attrs)
        try:
            yield span
        except Exception as e:
            span.record_exception(e)
            span.set_status(Status(StatusCode.ERROR))
            raise


__all__ = ["client_span"]

class TestClientToolTracing:
    """Tests for client tool call tracing."""

    async def test_call_tool_creates_span(self, trace_exporter: InMemorySpanExporter):
        server = FastMCP("test-server")

        @server.tool()
        def greet(name: str) -> str:
            return f"Hello, {name}!"

        client = Client(server)
        async with client:
            result = await client.call_tool("greet", {"name": "World"})
            assert "Hello, World!" in str(result)

        spans = trace_exporter.get_finished_spans()
…[8630 chars omitted]…
 = client_span.attributes.get("mcp.session.id")
        server_session = server_span.attributes.get("mcp.session.id")

        assert client_session is not None, "Client span should have session ID"
        assert server_session is not None, "Server span should have session ID"
        assert client_session == server_session, (
            "Client and server should share the same session ID"
        )

…[3159 chars omitted]…
.py:56:def server_span(
src/fastmcp/server/telemetry.py:100:def delegate_span(
src/fastmcp/server/telemetry.py:127:    "delegate_span",
src/fastmcp/server/telemetry.py:130:    "server_span",
src/fastmcp/settings.py:268:    mask_error_details: Annotated[
src/fastmcp/telemetry.py:76:def record_span_error(span: Span, exception: BaseException) -> None:
src/fastmcp/telemetry.py:121:    "record_span_error",

            version: Specific version to call. If None, calls highest version.
            run_middleware: If True (default), apply the middleware chain.
                Set to False when called from middleware to avoid re-applying.
            task_meta: If provided, execute as a background task and return
                CreateTaskResult. If None (default), execute synchronously and
                return ToolResult.

        Returns:
            ToolResult when task_meta is None.
        
…[8629 chars omitted]…
         FastMCPDeprecationWarning,
                stacklevel=2,
            )
        try:
            self._local_provider.remove_tool(name, version)
        except KeyError:
            if version is None:
                raise NotFoundError(f"Tool {name!r} not found") from None
            raise NotFoundError(
                f"Tool {name!r} version {version!r} not found"
            ) from None

                )

            # Core logic: find and execute tool (providers queried in parallel)
            # Use get_tool to apply transforms and filter disabled
            with server_span(
                f"tools/call {name}", "tools/call", self.name, "tool", name
            ) as span:
                # Try normal resolution first. If that fails and the name
                #
…[8629 chars omitted]…
 versions. If specified, removes only that version.

        Raises:
            NotFoundError: If no matching tool is found.
        """
        if fastmcp.settings.deprecation_warnings:
            warnings.warn(
                "remove_tool() is deprecated. Use "
                "mcp.local_provider.remove_tool(name) instead.",
                FastMCPDeprecationWarning,
                stacklevel=2,

                    fastmcp_context=ctx,
                )
                return await self._run_middleware(
                    context=mw_context,
                    call_next=lambda context: self.read_resource(
                        str(context.message.uri),
                        versio
…[2767 chars omitted]…
t_span_attributes())
                params = template.matches(uri)
                assert params is not None
                if task_meta is not None and task_meta.fn_key is None:
                    task_meta = replace(task_meta, fn_key=template.key)
                try:
                    return await template._read(uri, params, task_meta=task_meta)
                except (FastMCPError, McpError):

                content = await read_file(path)
                return [
                    {
                        "role": "user",
                        "content": {
                            "type": "resource",
                            "resource": {
                                "uri": f"file://{path}",
                                "text": content
                
…[7215 chars omitted]…
   prefix: Optional prefix to use for the imported server's objects. If None,
                objects are imported with their original names.
        """
        import warnings

        warnings.warn(
            "import_server is deprecated, use mount() instead",
            FastMCPDeprecationWarning,
            stacklevel=2,
        )

        def add_resource_prefix(uri: str, prefix: str) -> str:

    combined.add_provider(provider1)
    combined.add_provider(provider2, namespace="api")  # Tools become "api_foo"

    # Use like any other provider
    tools = await combined.list_tools()
    ```
"""

from __future__ import annotations

import logging
from collections.abc import AsyncIterator, Sequence
from contextlib import AsyncExitStack, asynccontextmanager
from typing import TYPE_CHECKING, TypeVar

from fastmcp.exceptions import NotFoundError
from f
…[8628 chars omitted]…
-------------------------------------------------------------
    # Tasks
    # -------------------------------------------------------------------------

    async def get_tasks(self) -> Sequence[FastMCPComponent]:
        """Get all task-eligible components from all providers."""
        results = await gather(
            *[p.get_tasks() for p in self.providers],
            return_exceptions=True,

            provider = provider.wrap_transform(Namespace(namespace))

        self.providers.append(provider)

    def _collect_list_results(
        self, results: list[Sequence[T] | BaseException], operation: str
    ) -> list[T]:
        """Collect successful list results, logging any exceptions."""
        collected: list[T] = []
        for i, result in enumerate(results):
            if isinstance(result, BaseException):
                logger.debug(
  
…[8629 chars omitted]…
rompt to delegate rendering to the server's middleware."""
        return cls(
            server=server,
            original_name=prompt.name,
            name=prompt.name,
            version=prompt.version,
            description=prompt.description,
            arguments=prompt.arguments,
            tags=prompt.tags,
            task_config=prompt.task_config,
            meta=prompt.get_meta(),

    @overload
    async def _run(
        self,
        arguments: dict[str, Any],
        task_meta: None = None,
    ) -> ToolResult: ...

    @overload
    async def _run(
        self,
        arguments: dict[str, Any],
        task_meta: TaskMeta,
    ) -> mcp.types.CreateTaskResult: ...

    async def _run(
        self,
        arguments: dict[str, Any],
        task_meta: TaskMeta | None = None,
    ) -> ToolResult | mcp.types.CreateTaskResult:
        """Delegate to 
…[8629 chars omitted]…
    ```python
        from fastmcp import FastMCP
        from fastmcp.server.providers import FastMCPProvider

        main = FastMCP("Main")
        sub = FastMCP("Sub")

        @sub.tool
        def greet(name: str) -> str:
            return f"Hello, {name}!"

        # Mount directly - tools accessible by original names
        main.add_provider(FastMCPProvider(sub))

        # Or with namespace

        """Start the mounted server's user lifespan.

        This starts only the wrapped server's user-defined lifespan, NOT its
        full _lifespan_manager() (which includes Docket). The parent server's
        Docket handles all background tasks.
        """
        async with self.server._lifespan(self.server):
            yield

    # Tool methods
    # -------------------------------------------------------------------------

    async def _list_tools(self) -> Sequence[Tool]:
        """List all tools from the mounted server as FastMCPProviderTools.

        Runs the mounted server's middleware so filtering/transformation applies.
        Wraps each tool as a FastMCPProviderTool that delegates execution to
        the nested server's middleware.
        """
        raw_tools = await self.server.list_tools()
        return [FastMCPProviderTool.wrap(self.server, t) for t in raw_tools]

    async def _get_too
…[8630 chars omitted]…
_config.mode != 'forbidden'.

        Used by the server during startup to register functions with Docket.
        """
        # Fetch all component types in parallel
        results = await gather(
            self._list_tools(),
            self._list_resources(),
            self._list_resource_templates(),
            self._list_prompts(),
        )
        tools = cast(Sequence[Tool], results[0])

src/fastmcp/utilities/versions.py:295:    """Deduplicate components by key, keeping highest version.
src/fastmcp/utilities/versions.py:301:        components: Sequence of components to deduplicate.
src/fastmcp/utilities/versions.py:305:        Deduplicated list with versions injected into meta.

                "remove_tool_transformation is deprecated and has no effect. "
                "Transforms are immutable once added. Use server.disable(keys=[...]) "
                "to hide tools instead.",
                FastMCPDeprecationWarning,
                stacklevel=2,
            )

    async def list_tools(self, *, run_middleware: bool = True) -> Sequence[Tool]:
        """List all enabled tools from providers.

        Overrides Provider.list_tools() t
…[8629 chars omitted]…
            except AuthorizationError:
                return None

        return prompt

    async def get_prompt(
        self, name: str, version: VersionSpec | None = None
    ) -> Prompt | None:
        """Get a prompt by name, filtering disabled prompts.

        Overrides Provider.get_prompt() to add visibility filtering after all
        transforms (including session-level) have been applied.

        """
        async with fastmcp.server.context.Context(fastmcp=self) as ctx:
            if run_middleware:
                mw_context = MiddlewareContext(
                    message={},
                    source="client",
                    type="request",
                    method="resources/list",
                    fastmcp_context=ctx,
                )
                return awa
…[4650 chars omitted]…

                    type="request",
                    method="resources/templates/list",
                    fastmcp_context=ctx,
                )
                return await self._run_middleware(
                    context=mw_context,
                    call_next=lambda context: self.list_resource_templates(
                        run_middleware=False
                    ),
                )

from fastmcp.exceptions import DisabledError, NotFoundError
from fastmcp.server.tasks.config import TaskMeta
from fastmcp.utilities.logging import get_logger
from fastmcp.utilities.pagination import paginate_sequence
from fastmcp.utilities.versions import VersionSpec, dedupe_with_versions

if TYPE_CHECKING:
    from fastmcp.server.server import FastMCP

logger = get_logger(__name__)

PaginateT = TypeVar("PaginateT")


def _apply_pagination(
    items: Sequence[PaginateT],
    cursor: str | None,
    page_size: int | None,
) -> tuple[list[Pa
…[8629 chars omitted]…
ewareServerSession

        server = cast("FastMCP", self)
        logger.debug(f"[{server.name}] Handler called: set_logging_level %s", level)
        try:
            ctx = server._mcp_server.request_context
            session = ctx.session
            if isinstance(session, MiddlewareServerSession):
                session._minimum_logging_level = level
        except LookupError:
            pass

    async def _list_resource_templates_mcp(
        self, request: mcp.types.ListResourceTemplatesRequest
    ) -> mcp.types.ListResourceTemplatesResult:
        """
        List all available resource templates, in the format expected by the low-level MCP
        server. Supports pagination when list_page_size is configured.
        """
        server = cast("FastMCP", self)
     
…[8260 chars omitted]…
           return result.to_mcp_prompt_result()
        except DisabledError as e:
            raise NotFoundError(f"Unknown prompt: {name!r}") from e
        except NotFoundError:
            raise

    async def _set_logging_level_mcp(self, level: mcp.types.LoggingLevel) -> None:
        """Handle MCP 'logging/setLevel' requests.

        Stores the requested minimum log level on the session so that

            description="Maximum time to wait for a clean disconnect before giving up, in seconds.",
        ),
    ] = 5

    # Transport settings
    transport: Literal["stdio", "http", "sse", "streamable-http"] = "stdio"

    # HTTP settings
    host: str = "127.0.0.1"
    port: int = 8000
    sse_path: str = "/sse"
    message_path: str = "/messages/"
    streamable_http_path: str = "/mcp"
    debug: bool = False

    # error handling
    mask_error_details: Annotated[
        bool,
        Field(
            description=inspect.cleandoc(
                """
                If Tr
…[1052 chars omitted]…
tmcp/server/server.py:326:        self._mask_error_details: bool = (
src/fastmcp/server/server.py:1183:                    if self._mask_error_details:
src/fastmcp/server/server.py:1297:                        if self._mask_error_details:
src/fastmcp/server/server.py:1336:                    if self._mask_error_details:
src/fastmcp/server/server.py:1434:                    if self._mask_error_details:

        name: str | None = None,
        instructions: str | None = None,
        *,
        version: str | int | float | None = None,
        website_url: str | None = None,
        icons: list[mcp.types.Icon] | None = None,
        auth: AuthProvider | None = None,
        middleware: Sequence[Middleware] | None = None,
        providers: Sequence[Provider] | None = None,
        transforms: Sequence[Transform] | None = None,
        lifespan: LifespanCallable | Lifespan | None = None,
        tools: Sequence[Tool | Callable[..., Any]] | None = None,
        on_duplicate: DuplicateBehavior | None = None,
        mask_error_details: bool | None = None,
        dereference_schemas: bool = True,
        s
…[8629 chars omitted]…
n self._local_provider.add_tool(tool)

    def remove_tool(self, name: str, version: str | None = None) -> None:
        """Remove tool(s) from the server.

        .. deprecated::
            Use ``mcp.local_provider.remove_tool(name)`` instead.

        Args:
            name: The name of the tool to remove.
            version: If None, removes ALL versions. If specified, removes only that version.

            version: Specific version to call. If None, calls highest version.
            run_middleware: If True (default), apply the middleware chain.
                Set to False when called from middleware to avoid re-applying.
            task_meta: If provided, execute as a background task and return
                CreateTaskResult. If None (default), execute synchronously and
                return ToolResult.

        Returns:
            ToolResult when task_meta is None.
        
…[6250 chars omitted]…
erent key formats:
        # - Resources use resource.key (derived from the concrete URI)
        # - Templates use template.key (the template pattern)
        # For mounted servers, the parent's provider sets fn_key to the
        # namespaced key before delegating, ensuring correct Docket routing.

        async with fastmcp.server.context.Context(fastmcp=self) as ctx:
            if run_middleware:

    from fastmcp.client.client import Client

from fastmcp.client.tasks import ResourceTask
from fastmcp.client.telemetry import client_span
from fastmcp.telemetry import inject_trace_context
from fastmcp.utilities.logging import get_logger

logger = get_logger(__name__)

AUTO_PAGINATION_MAX_PAGES = 250

# Type alias for task response union (SEP-1686 graceful degradation)
ResourceTaskResponseUnion = RootModel[
    mcp.types.CreateTaskResult | mcp.types.ReadResourceResult
]


class ClientResourcesMixin:
    """Mixin providing resource-related methods for Client."""

    # --- Resources ---

    async def list_resources_mcp(
        self: Clie
…[8629 chars omitted]…
PromptResult: ...

    @overload
    async def get_prompt(
        self: Client,
        name: str,
        arguments: dict[str, Any] | None = None,
        *,
        version: str | None = None,
        meta: dict[str, Any] | None = None,
        task: Literal[True],
        task_id: str | None = None,
        ttl: int = 60000,
    ) -> PromptTask: ...

    async def get_prompt(
        self: Client,

        *,
        version: str | None = None,
        timeout: datetime.timedelta | float | int | None = None,
        progress_handler: ProgressHandler | None = None,
        raise_on_error: bool = T
…[8628 chars omitted]…
    else:
                data = structured_content
        except Exception as e:
            logger.error(
                f"[{client_name or 'client'}] Error parsing structured content: {e}"
            )

    return CallToolResult(
        content=result.content,
        structured_content=result.structuredContent,
        meta=result.meta,
        data=data,
        is_error=result.isError,
    )

class TestFastMCPProviderTracing:
    """Tests for FastMCPProvider delegation tracing."""

    async def test_mounted_tool_creates_delegate_span(
        self, trace_exporter: InMemorySpanExporter
    ):
        # Create a child server with a tool
        child = FastMCP("child-server")

        @child.tool()
        def child_tool() -> str:
            return "child result"

        # Create parent server and mount child with namespace
        parent = FastMCP("parent-server")
        parent.mount(child, namesp
…[3825 chars omitted]…
s in spans if s.name == "delegate greet")
        child_span = next(s for s in spans if s.name == "tools/call greet")

        # Verify parent-child relationships
        assert delegate_span.parent is not None
        assert child_span.parent is not None
        assert delegate_span.parent.span_id == parent_span.context.span_id
        assert child_span.parent.span_id == delegate_span.context.span_id

from fastmcp.server.auth import AccessToken


class TestToolTracing:
    async def test_call_tool_creates_span(self, trace_exporter: InMemorySpanExporter):
        mcp = FastMCP("test-server")

        @mcp.tool()
        def greet(name: str) -> str:
            return f"Hello, {name}!"

        result = await mcp.call_tool("greet", {"name": "World"})
        assert "Hello, World!" in str(result)

        spans = trace_exporter.get_finished_spans()
        assert len(spans) == 1

        span = spans[0]
        assert span.name =
…[8629 chars omitted]…
          await mcp.call_tool("greet", {"name": "World"})

        spans = trace_exporter.get_finished_spans()
        assert len(spans) == 1

        span = spans[0]
        assert span.attributes is not None
        assert span.attributes["enduser.id"] == "client-no-scopes"
        # Scope attribute should not be present when scopes list is empty
        assert "enduser.scope" not in span.attributes

class TestClientToolTracing:
    """Tests for client tool call tracing."""

    async def test_call_tool_creates_span(self, trace_exporter: InMemorySpanExporter):
        server = FastMCP("test-server")

        @server.tool()
        def greet(name: str) -> str:
            return f"Hello, {name}!"

        client = Client(server)
        async with client:
            result = await client.call_tool("greet", {"name": "World"})
            assert "Hello, World!" in str(result)

        spans = trace_exporter.get_finished_spans()
…[8630 chars omitted]…
 = client_span.attributes.get("mcp.session.id")
        server_session = server_span.attributes.get("mcp.session.id")

        assert client_session is not None, "Client span should have session ID"
        assert server_session is not None, "Server span should have session ID"
        assert client_session == server_session, (
            "Client and server should share the same session ID"
        )

        # Find client span (no fastmcp.server.name) and server span (has fastmcp.server.name)
        client_span = next(
            (
                s
                for s in spans
                if s.name == "tools/call echo"
                and s.attributes is not None
                and "fastmcp.server.name" not in s.attributes
            ),
            None,
        )
        server_span = next(
            (
                s
                for s in spans
                if s.name == "tools/call echo"
                and s.attributes is not None
                and "fas
…[7599 chars omitted]…
ver_span is not None, "Server should create a span"

        # Server span should have ERROR status
        assert server_span.status.status_code == StatusCode.ERROR

    async def test_call_nonexistent_tool_creates_spans(
        self, trace_exporter: InMemorySpanExporter
    ):
        """Both client and server spans should be created for nonexistent tool."""
        server = FastMCP("test-server")

    exporter.clear()


@pytest.fixture
def fastmcp_server():
    """Fixture that creates a FastMCP server with tools, resources, and prompts."""
    import asyncio
    import json

    from fastmcp import FastMCP

    server = FastMCP("TestServer")

    # Add a tool
    @server.tool
    def greet(name: str) -> str:
        """Greet someone by name."""
        return f"Hello, {name}!"

For more features, use [Jaeger](https://www.jaegertracing.io/):

```bash
docker run -d --name jaeger \
  -p 16686:16686 \
  -p 4317:4317 \
  jaegertracing/all-in-one:latest
```

Then view traces at http://localhost:16686

## Custom Spans

You can add your own spans using the FastMCP tracer:

```python
from fastmcp import FastMCP
from fastmcp.telemetry import get_tracer

mcp = FastMCP("custom-spans")

@mcp.tool()
async def complex_operation(input: str) -> str:
    tracer = get_tracer()

    with tracer.start_as_current_span("parse_input") as span:
        span.set_attribute("input.length", len(input))
        parsed = p
…[2534 chars omitted]…
 import Generator
from opentelemetry import trace
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 fastmcp import FastMCP

@pytest.fixture
def trace_exporter() -> Generator[InMemorySpanExporter, None, None]:
    exporter = InMemorySpanExporter()

tests/server/auth/providers/test_propelauth.py
tests/server/auth/providers/test_scalekit.py
tests/server/auth/providers/test_supabase.py
tests/server/auth/providers/test_workos.py
tests/server/providers/__init__.py
tests/server/providers/local_provider_tools/__init__.py
tests/server/providers/local_provider_tools/test_context.py
tests/server/providers/local_provider_t
…[4272 chars omitted]…
m AggregateProvider (handles aggregation and namespacing)
src/fastmcp/server/server.py:978:        Extends AggregateProvider._get_prompt() with component-level auth checks.
src/fastmcp/server/server.py:987:        # Get prompt from AggregateProvider (handles aggregation and namespacing)
src/fastmcp/server/server.py:1999:        # Use add_provider with namespace (applies namespace in AggregateProvider)

tests/server/providers/test_transforming_provider.py:127:        with pytest.raises(ValueError, match="duplicate target name"):

@provider.tool
def greet(name: str) -> str:
    return f"Hello, {name}!"

# Attach to any server
from fastmcp import FastMCP
server1 = FastMCP("Server1", providers=[provider])
server2 = FastMCP("Server2", providers=[provider])
```
"""

from __future__ import annotations

from collections.abc import Sequence
from typing import Literal, TypeVar

from fastmcp.prompts.base import Prompt
from fastmcp.resources.base import Resource
from fastmcp.resources.template import ResourceTemplate
from fas
…[6969 chars omitted]…
CPComponent | None:
        """Get a component by its prefixed key.

        Args:
            key: The prefixed key (e.g., "tool:name", "resource:uri").

        Returns:
            The component, or None if not found.
        """
        return self._components.get(key)

    def remove_tool(self, name: str, version: str | None = None) -> None:
        """Remove tool(s) from this provider's storage.

    key_fn: Callable[[C], str],
) -> list[C]:
    """Deduplicate components by key, keeping highest version.

    Groups components by key, selects the highest version from each group,
    and injects available versions into meta if any component is versioned.

    Args:
        components: Sequence of components to deduplicate.
        key_fn: Function to extract the grouping key from a component.

    Returns:
        Deduplicated list with versions injected into meta.
    """
    by_key: dict[str, list[C]] = {}
    for c in components:
        by_key.setdefault(key_fn(c), []).append(c)

    result: list[C] = []
    for versions in b
…[367 chars omitted]…
            highest = highest.model_copy(
                update={
                    "meta": {
                        **meta,
                        "fastmcp": {
                            **meta.get("fastmcp", {}),
                            "versions": all_versions,
                        },
                    }
                }
            )
        result.append(highest)
    return result

DEBUG:mcp.server.lowlevel.server:Registering handler for SetLevelR
…[755 chars omitted]…
eta={'fastmcp': {'tags': []}} task_config=TaskConfig(mode='forbidden', poll_interval=datetime.timedelta(seconds=5)) parameters={'additionalProperties': False, 'properties': {}, 'type': 'object'} output_schema=None annotations=None execution=None serializer=None auth=None timeout=None
call result content=[TextContent(type='text', text='a', annotations=None, meta=None)] structured_content=None meta=None

    combined.add_provider(provider1)
    combined.add_provider(provider2, namespace="api")  # Tools become "api_foo"

    # Use like any other provider
    tools = await combined.list_tools()
    ```
"""

from __future__ import annotations

import logging
from collections.abc import AsyncIterator, Sequence
from contextlib import AsyncExitStack, asynccontextmanager
from typing import TYPE_CHECKING, TypeVar

from fastmcp.exceptions import NotFoundError
from f
…[8628 chars omitted]…
----------------
    # Lifecycle
    # -------------------------------------------------------------------------

    @asynccontextmanager
    async def lifespan(self) -> AsyncIterator[None]:
        """Combine lifespans of all providers."""
        async with AsyncExitStack() as stack:
            for p in self.providers:
                await stack.enter_async_context(p.lifespan())
            yield

            output_schema=mcp_tool.outputSchema,
            icons=mcp_tool.icons,
            meta=mcp_tool.meta,
            tags=get_fastmcp_metadata(mcp_tool.meta).get("tags", []),
            execution=mcp_tool.execution,
        )

    async def run(
        self,
        arguments: dict[str, Any],
        context: Context | None = None,
    ) -> ToolResult:
        """Executes the tool by making a call through t
…[3473 chars omitted]…
            # (not the static prompt meta which includes fastmcp tags)
            # Convert PromptMessages to Messages
            messages = [
                Message(content=m.content, role=m.role) for m in result.messages
            ]
            return PromptResult(
                messages=messages,
                description=result.description,
                meta=result.meta,
            )

…[7385 chars omitted]…
istent', 'mcp.session.id': 'd2260773-e6be-4350-a37e-2db776a8623c'} StatusCode.ERROR NotFoundError: Unknown prompt: 'nonexistent' ['exception', 'exception']
prompts/get nonexistent SpanKind.CLIENT {'rpc.system': 'mcp', 'rpc.method': 'prompts/get', 'mcp.method.name': 'prompts/get', 'fastmcp.component.key': 'nonexistent'} StatusCode.ERROR McpError: Unknown prompt: 'nonexistent' ['exception', 'exception']

            ToolTask: Future-like object for accessing task status and results
        """
        # Per SEP-1686 final spec: client sends only ttl, server generates taskId
        # Inject trace context into meta for propagation to server
        propagated_meta = inject_trace_context(met
…[8628 chars omitted]…
      *,
        version: str | None = None,
        meta: dict[str, Any] | None = None,
        task: Literal[True],
        task_id: str | None = None,
        ttl: int = 60000,
    ) -> ResourceTask: ...

    async def read_resource(
        self: Client,
        uri: AnyUrl | str,
        *,
        version: str | None = None,
        meta: dict[str, Any] | None = None,
        task: bool = False,

tests/server/mount/test_proxy.py:304:        # Lifespan is executed at least once (may be multiple times for proxy connections)
tests/server/mount/test_proxy.py:305:        assert len(lifespan_check) >= 1
tests/server/mount/test_proxy.py:306:        assert all(x == "start" for x in lifespan_check)

from collections.abc import Awaitable, Callable, Sequence
from typing import TYPE_CHECKING, Any, cast
from urllib.parse import quote

import mcp.types
from mcp import ServerSession
from mcp.client.session import ClientSession
from mcp.server.lowlevel.server import request_ctx
from mcp.shared.context import LifespanContextT, RequestContext
from mcp.shared.exceptions import McpError
from mcp.types import (
    METHOD_NOT_FOUND,
    BlobResourceContents,
    ElicitRequestFormParams,
    TextResourceContents,
)
from pydantic.networks import AnyUrl

from fast
…[8629 chars omitted]…
    super().__init__(**kwargs)
        self._client_factory = client_factory

    async def _get_client(self) -> Client:
        """Gets a client instance by calling the sync or async factory."""
        client = self._client_factory()
        if inspect.isawaitable(client):
            client = cast(Client, await client)
        return client

    def model_copy(self, **kwargs: Any) -> ProxyTemplate:

                    if hasattr(req_ctx, "meta") and req_ctx.meta:
                        meta = dict(req_ctx.meta)
                    # Add task metadata if this is a task request
                    if (
                        hasatt
…[2297 chars omitted]…
uri is None:
            # First time uri is being changed, preserve original for backend calls
            update = {**update, "_backend_uri": str(self.uri)}
            kwargs["update"] = update
        return super().model_copy(**kwargs)

    @classmethod
    def from_mcp_resource(
        cls,
        client_factory: ClientFactoryT,
        mcp_resource: mcp.types.Resource,
    ) -> ProxyResource:

tests/server/auth/test_authorization.py:235:        """Async checks that raise non-AuthorizationError should be masked."""

src/fastmcp/cli/install/goose.py:16:logger = get_logger(__name__)
src/fastmcp/cli/install/mcp_json.py:17:logger = get_l
…[5049 chars omitted]…
(handler)
    logger.addHandler(traceback_handler)


@contextlib.contextmanager
def temporary_log_level(
    level: str | None,
    logger: logging.Logger | None = None,
    enable_rich_tracebacks: bool | None = None,
    **rich_kwargs: Any,
):
    """Context manager to temporarily set log level and restore it afterwards.

    Args:
        level: The temporary log level to set (e.g., "DEBUG", "INFO")

from fastmcp.server.providers.base import Provider
from fastmcp.utilities.versions import VersionSpec

if TYPE_CHECKING:
    from fastmcp.prompts.base import Prompt
    from fastmcp.resources.base import Resource
    from fastmcp.resources.template import ResourceTemplate
    from fastmcp.server.transforms import Transform
    from fastmcp.tools.base import Tool
    from fastmcp.utilities.components import FastMCPComponent


class _WrappedProvider(Provider):
    """Internal provider that wraps another provider wit
…[4689 chars omitted]…
ks()
        ]

    # -------------------------------------------------------------------------
    # Lifecycle - combine with inner
    # -------------------------------------------------------------------------

    @asynccontextmanager
    async def lifespan(self) -> AsyncIterator[None]:
        """Combine lifespan with inner provider."""
        async with self._inner.lifespan():
            yield

</ParamField>

<ParamField body="strict_input_validation" type="bool" default="False">
  <VersionBadge version="2.13.0" />

  When `False` (default), FastMCP uses Pydantic's flexible validation that coerces compatible inputs (e.g., `"10"` → `10` for int parameters). When `True`, validates inputs against the exact JSON Schema before calling your function, rejecting type mismatches. See [Input V
…[3296 chars omitted]…
   async def _ensure_discovered(self) -> None:
        """Ensure skills are discovered, rediscovering if reload is enabled."""
        if self._reload or not self._discovered:
            self._discover_skills()

    # Override list methods to support reload
    async def _list_resources(self) -> Sequence[Resource]:
        await self._ensure_discovered()
        return await super()._list_resources()

    Callable,
    Sequence,
)
from contextlib import (
    AbstractAsyncContextManager,
    asynccontextmanager,
)
from dataclasses import replace
from functools import partial
from pathlib import Path
from typing import TYPE_CHECKING, Any, Generic, Literal, TypeVar, cast, overload

import httpx
import mcp.types
from key_value.aio.adapters.pydantic import PydanticAdapter
from key_value.aio.protocols import AsyncKeyValue
from key_value.aio.stores.memory import MemoryStore
from mcp.server.lowlevel.server import LifespanResultT
from mcp.shared.exceptions import McpError
from mcp.types import (
    Annotations,
    AnyFunction,
    CallToolRequestParams,
    To
…[3521 chars omitted]…
MCP_MESSAGE_PATH.",
    "streamable_http_path": "Pass `path` to `run_http_async()` or `http_app()`, or set FASTMCP_STREAMABLE_HTTP_PATH.",
    "json_response": "Pass `json_response` to `run_http_async()` or `http_app()`, or set FASTMCP_JSON_RESPONSE.",
    "stateless_http": "Pass `stateless_http` to `run_http_async()` or `http_app()`, or set FASTMCP_STATELESS_HTTP.",
    "debug": "Set FASTMCP_DEBUG.",

    SettingsConfigDict,
)

from fastmcp.utilities.logging import get_logger

logger = get_logger(__name__)

ENV_FILE = os.getenv("FASTMCP_ENV_FILE", ".env")

LOG_LEVEL = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]

MCP_LOG_LEVEL = Literal[
    "debug", "info", "notice", "warning", "error", "critical", "alert", "emergency"
]

DuplicateBehavior = Literal["warn", "error", "replace", "ignore"]

TEN_MB_IN_BYTES = 1024 * 1024 * 10


class DocketSettings(BaseSettings):
    """Docket worker configuration."""

    model_config = SettingsConfigDict(
        env_prefix="FASTMCP_
…[279 chars omitted]…
 a task queue.
                """
            ),
        ),
    ] = "fastmcp"

    url: Annotated[
        str,
        Field(
            description=inspect.cleandoc(
                """
                URL for the Docket backend. Supports:
                - memory:// - In-memory backend (single process only)
                - redis://host:port/db - Redis/Valkey backend (distributed, multi-process)

tests/server/providers/test_local_provider.py:804:        server = FastMCP("Test", providers=[provider])
tests/server/providers/test_local_provider.py:822:        server = FastMCP("Test", providers=[provider])

class FastMCPError(Exception):
    """Base error for FastMCP."""


class ValidationError(FastMCPError):
    """Error in validating parameters or return values."""


class ResourceError(FastMCPError):
    """Error in resource operations."""


class ToolError(FastMCPError):
    """Error in tool operations."""


class PromptError(FastMCPError):
    """Error in prompt operations."""


class InvalidSignature(Exception):
    """Invalid signature for use with FastMCP."""


class ClientError(Exception):
    """Error in client operations."""


class NotFoundError(Exception):
    """Object not found."""


class DisabledError(Exception):
    """Object is disabled."""


class AuthorizationError(FastMCPError):
    """Error when authorization check fails."""

    from fastmcp.apps.app import FastMCPApp as FastMCPApp

settings = Settings()
if settings.log_enabled:
    _configure_logging(
        level=settings.log_level,
        enable_rich_tracebacks=settings.enable_rich_tracebacks,
    )

from fastmcp.exceptions import FastMCPDeprecationWarning
from fastmcp.server.server import FastMCP
from fastmcp.server.context import Context
import fastmcp.server

__version__ = _version("fastmcp")

if settings.deprecation_warnings:
    warnings.simplefilter("default", FastMCPDeprecationWarning)


# --- Lazy impor
…[1255 chars omitted]…
om fastmcp.telemetry import inject_trace_context
src/fastmcp/client/mixins/resources.py:17:from fastmcp.telemetry import inject_trace_context
src/fastmcp/client/mixins/tools.py:20:from fastmcp.telemetry import inject_trace_context
src/fastmcp/client/telemetry.py:8:from fastmcp.telemetry import get_tracer
src/fastmcp/server/telemetry.py:10:from fastmcp.telemetry import extract_trace_context, get_tracer

            arguments=arguments,
            icons=mcp_prompt.icons,
            meta=mcp_prompt.meta,
            tags=get_fastmcp_metadata(mcp_prompt.meta).get("tags", []),
            task_config=TaskConfig(mode="forbidden"),
        )

    async def render(self, arguments: dict[str, Any]) -> PromptResult:  # type: ignore[override]  # ty:ignore[invalid-method-override]
        """Render the prompt by making a call through the client."""
        backend_name = self._backend_name or s
…[2916 chars omitted]…
ed() and type(client) is ProxyClient:
771:                return client.new()
775:        if client.is_connected():
787:            return client.new()
795:            return base_client.new()
1012:        from fastmcp.client.transports.http import StreamableHttpTransport
1013:        from fastmcp.client.transports.sse import SSETransport
1092:                await proxy_client._disconnect(force=True)

    ) -> ProxyTemplate:  # ty:ignore[invalid-method-override]
        """Factory method to create a ProxyTemplate from a raw MCP template schema."""

        return cls(
            client_factory=client_factory,
            uri_templat
…[1773 chars omitted]…
meType,
                        meta=item.meta,
                    )
                )
            elif isinstance(item, BlobResourceContents):
                contents.append(
                    ResourceContent(
                        content=base64.b64decode(item.blob),
                        mime_type=item.mimeType,
                        meta=item.meta,
                    )
                )

    combined.add_provider(provider1)
    combined.add_provider(provider2, namespace="api")  # Tools become "api_foo"

    # Use like any other provider
    tools = await combined.list_tools()
    ```
"""

from __future__ import annotations

import logging
from collections.abc import AsyncIterator, Sequence
from contextlib import AsyncExitStack, asynccontextmanager
from typing import TYPE_CHECKING, Literal, TypeVar

from fastmcp.exceptions import NotFoundErr
…[6679 chars omitted]…


    def __repr__(self) -> str:
        return f"AggregateProvider(providers={self.providers!r})"

    # -------------------------------------------------------------------------
    # Tools
    # -------------------------------------------------------------------------

    async def _list_tools(self) -> Sequence[Tool]:
        """List all tools from all providers."""
        results = await gather(

            raise ValueError(message)
        if self._on_duplicate == "warn":
            logger.warning(message)
            return "replace"
        if self._on_duplicate == "ignore":
            return "ignore"
        return "replace"

    def _collect_list_results(
        self, results: list[Sequence[T] | BaseException]
…[2965 chars omitted]…
p.list_tools() for p in self.providers],
            return_exceptions=True,
        )
        return self._collect_list_results(results, "list_tools")

    async def _get_tool(
        self, name: str, version: VersionSpec | None = None
    ) -> Tool | None:
        """Get tool by name from providers."""
        results = await gather(
            *[p.get_tool(name, version) for p in self.providers],

        self._additional_http_routes: list[BaseRoute] = []

        # Session-scoped state store (shared across all requests)
        self._state_storage: AsyncKeyValue = session_state_store or MemoryStore()
        self._state_store: PydanticAdapter[StateValue] = PydanticAdapter[StateValue](
            key_value=self._state_storage,
            pydantic_model=StateValue,
            default
…[171 chars omitted]…
licate=self._on_duplicate
        )

        # Add providers using AggregateProvider's add_provider
        # LocalProvider is always first (no namespace)
        self.add_provider(self._local_provider)
        for p in providers or []:
            self.add_provider(p)

        for t in transforms or []:
            self.add_transform(t)

        # Store mask_error_details for execution error handling

                    return await tool._run(arguments or {}, task_meta=task_meta)
                except FastMCPError:
                    logger.exception(f
…[8054 chars omitted]…
@tool decorator for examples.

        Args:
            tool: The Tool instance or @tool-decorated function to register

        Returns:
            The tool instance that was added to the server.
        """
        return self._local_provider.add_tool(tool)

    def remove_tool(self, name: str, version: str | None = None) -> None:
        """Remove tool(s) from the server.

        .. deprecated::

255:        fn: The function
…[3579 chars omitted]…
       ```python
        ArgTransform(default=42)
        ```

        Add a default factory (makes argument optional)
        ```python
        ArgTransform(default_factory=lambda: time.time())
        ```

        Change the type
        ```python
        ArgTransform(type=str)
        ```

        Hide the argument entirely from clients
        ```python
        ArgTransform(hide=True)
        ```

        seen.add(id(current))
        if getattr(current, "_server", None) is not None:
            return True
        current = getattr(current, "parent_tool", None)
    return False


_REMOVED_KWARGS: dict[str, str] = {
    "host": "Pass `host` to `run_http_async()`, or set FASTMCP_HOST.",
    "port": "Pass `port` to `run_http_async()`, or set FASTMCP_PORT.",
    "sse_path": "Pass `path` to `run_http_async()` or `http_app()`, or set FASTMCP_SSE_PATH.",
    "message_path": "Set FASTMCP_MESSAGE_PATH.",
    "streamable_http_path": "Pass `pa
…[3974 chars omitted]…
mpatibility
            if as_proxy:
                from fastmcp.server.providers.proxy import FastMCPProxy

                if not isinstance(server, FastMCPProxy):
                    server = FastMCP.as_proxy(server)

        if self._mask_error_details and not server._mask_error_details:
            logger.warning(
                "Server %r has mask_error_details=True but mounted server %r has "

                "may be exposed to clients; consider setting "
                "mask_error_details=True on %r.",
                self.name,
                server.name,
                server.name,
            )

        # Create provider and add it with namespace
        provider: Provider = FastMCPProvider(server)

        # Apply tool renames first (scoped to this provider), then namespace
        # So foo → bar with namespace="baz" becomes baz_bar
        if tool_names:
            transforms = {
                old_name: ToolTransformConfig(name=new_name)
                for old_name, new_name in tool_names.items()
            }
            provider = provider.wrap_transform(ToolTransform(transforms))

    """Return the semantic error type for an exception."""
    from fastmcp.exceptions import ToolError

    if isinstance(exception, ToolError):
        return "tool_error"
    return type(exception).__name__


def set_span_error(span: Span, message: str, error_type: str) -> None:
    """Mark a span as failed with an error type and description."""
    span.set_attribute("error.type", error_type)
    span.set_status(Status(StatusCode.ERROR, message))


def record_span_error(
    span: Span,
    exception: BaseException,
 
…[1181 chars omitted]…
if TRACE_STATE_KEY in meta:
        carrier["tracestate"] = str(meta[TRACE_STATE_KEY])

    if carrier:
        return propagate.extract(carrier)
    return otel_context.get_current()


__all__ = [
    "INSTRUMENTATION_NAME",
    "TRACE_PARENT_KEY",
    "TRACE_STATE_KEY",
    "error_type_for_exception",
    "extract_trace_context",
    "get_tracer",
    "inject_trace_context",
    "record_span_error",

def get_auth_span_attributes() -> dict[str, str]:
    """Get auth attributes for the current request, if authenticated."""
    from fastmcp.server.dependencies import get_access_token

    attrs: dict[str, str] = {}
    try:
        token = get_access_token()
        if token:
            if token.client_id:
                attrs["enduser.id"] = token.client_id
            if token.scopes:
                attrs["enduser.scope"] = " ".join(token.scopes)
    except RuntimeError:
        pass
    return attrs


def get_session_span_attributes() -> dict[
…[2630 chars omitted]…
ibutes(
            {
                "fastmcp.provider.type": provider_type,
                "fastmcp.component.key": component_key,
            }
        )
        try:
            yield span
        except Exception as e:
            record_span_error(span, e)
            raise


__all__ = [
    "delegate_span",
    "get_auth_span_attributes",
    "get_session_span_attributes",
    "server_span",
]

    name: str,
    method: str,
    component_key: str,
    session_id: str | None = None,
    resource_uri: str | None = None,
) -> Generator[Span, None, None]:
    """Create a CLIENT span with standard MCP attributes.

    Automatically records any exception on the span and sets error status.
    """
    tracer = get_tracer()
    with tracer.start_as_current_span(
        name,
        kind=SpanKind.CLIENT,
        record_exception=False,
        set_status_on_exception=False,
    ) as span:
        attrs: dict[str, str] = {
            # MCP semantic conventions
            "mcp.method.name": method,
            # FastMCP-specif
…[191 chars omitted]…
ompts/get":
            attrs["gen_ai.prompt.name"] = component_key
        if session_id:
            attrs["mcp.session.id"] = session_id
        if resource_uri:
            attrs["mcp.resource.uri"] = resource_uri
        span.set_attributes(attrs)
        try:
            yield span
        except Exception as e:
            record_span_error(span, e)
            raise


__all__ = ["client_span"]

            RuntimeError: If called while the client is not connected.
            McpEr
…[1046 chars omitted]…
                    result.content[0], mcp.types.TextContent
                ):
                    message = result.content[0].text
                span.set_attribute("error.type", "tool_error")
                set_span_error(span, message, "tool_error")
            return result

    async def _parse_call_tool_result(
        self: Client,
        name: str,
        result: mcp.types.CallToolResult,

…[4856 chars omitted]…
stent'
--- client prompt nonexist 2
prompts/get nonexistent SERVER {'mcp.method.name': 'prompts/get', 'fastmcp.server.name': 'srv', 'gen_ai.prompt.name': 'nonexistent', 'error.type': 'NotFoundError'} ERROR "Unknown prompt: 'nonexistent'"
prompts/get nonexistent CLIENT {'mcp.method.name': 'prompts/get', 'gen_ai.prompt.name': 'nonexistent', 'error.type': 'McpError'} ERROR "Unknown prompt: 'nonexistent'"

            ctx = context or get_context()
            # StatefulProxyClient reuses sessions across requests, so
            # its receive-loop task has stale ContextVars from the first
            # request. Stash the current RequestContext in the shared
            # ref so handlers can restore it before forwarding.
            if isinstance(client, StatefulProxyClient):
                client._proxy_rc_ref[0] = (
                    ctx.request_context,
                    ctx._fastmcp,  # weakref to FastMCP, not 
…[6602 chars omitted]…
  # Convert GetPromptResult to PromptResult, preserving meta from result
        # (not the static prompt meta which includes fastmcp tags)
        # Convert PromptMessages to Messages
        messages = [Message(content=m.content, role=m.role) for m in result.messages]
        return PromptResult(
            messages=messages,
            description=result.description,
            meta=result.meta,

…[4444 chars omitted]…
 already exists
call err ValueError Duplicate get tool('ns foo') name 'tool:ns_foo@' found while aggregating providers; component already exists
mode warn
tools [('ns_foo', 'tool:ns_foo@')]
get tool:ns_foo@
call content=[TextContent(type='text', text='b', annotations=None, meta=None)] structured_content=None meta=None
child mask after mount False
masked err ToolError Error calling tool 'c_secret_tool'

…[8629 chars omitted]…
/fastmcp/prompts/function_prompt.py:337 in      │
                    │ render                                                   │
                    ╰──────────────────────────────────────────────────────────╯
                    PromptError: Error rendering prompt p.                      
resource ResourceError Error reading resource 'data://c/secret'
prompt PromptError Error rendering prompt 'c_p'

src/fastmcp/client/transports/stdio.py:2
…[7567 chars omitted]…
_/aggregate.cpython-312.pyc: binary file matches
src/fastmcp/server/providers/aggregate.py:12:    combined = AggregateProvider()
src/fastmcp/server/providers/aggregate.py:48:class AggregateProvider(Provider):
src/fastmcp/server/providers/aggregate.py:62:        combined = AggregateProvider()
src/fastmcp/server/providers/aggregate.py:216:        return f"AggregateProvider(providers={self.providers!r})"

FAILED tests/server/providers/test_local_provider.py::TestLocalProviderTaskRegistration::test_get_tasks_returns_task_eligible_tools
FAILED tests/server/providers/test_local_provider.py::TestLocalProviderStandaloneUsage::test_local_provider_first_wins_duplicates
33 failed, 572 passed, 33 warnings in 13.93s

tests/server/providers/local_provider_tools/test_output_schema.py:61: AssertionError
_____________ TestToolOutputSchema.test_simple_output_schema[bool] _____________

self = <tests.server.providers.local_provider_tools.test_output_schema.TestToolOutputSchema object at 0x7062df5f5490>
annotation = <class 'bool'>

    @pytest.mark.parametrize("annotation", [str, int, float, bo
…[4278 chars omitted]…

FAILED tests/server/providers/local_provider_tools/test_output_schema.py::TestToolOutputSchema::test_simple_output_schema[bool]
FAILED tests/server/providers/local_provider_tools/test_output_schema.py::TestToolOutputSchema::test_simple_output_schema[list]
FAILED tests/server/providers/local_provider_tools/test_output_schema.py::TestToolOutputSchema::test_simple_output_schema[AnyUrl]
8 failed in 1.83s

        @first_app.tool(name="shared_tool")
        def first_shared_tool() -> str:
            return "First app tool"
    
        @second_app.tool(name="shared_tool")
        def second_shared_tool() -> str:
            return "Second app tool"
    
        # Mount both apps without pref
…[8628 chars omitted]…
a
  Unexpected keyword argument [type=unexpected_keyword_argument, input_value='abc', input_type=str]
    For further information visit https://errors.pydantic.dev/2.14/v/unexpected_keyword_argument
=========================== short test summary info ============================
FAILED tests/server/providers/proxy/test_proxy_server.py::TestTools::test_proxy_can_overwrite_proxied_tool
1 failed in 1.47s

FAILED tests/server/providers/test_local_provider.py::TestLocalProviderTaskRegistration::test_get_tasks_returns_task_eligible_tools
16 failed, 589 passed, 33 warnings in 12.20s

        # Verify that errors were logged for the unreachable provider (at DEBUG level)
        debug_messages = [
            record.message for record in caplog.records if record.levelname == "DEBUG"
        ]
>       assert any(
            "Error during list_tools from provider" in msg for msg in debug_messages
        )
E       assert False
E        +  where False = any(<generator object TestMultipleServerMo
…[7584 chars omitted]…
=================
FAILED tests/server/mount/test_advanced.py::TestMountedServerDocketBehavior::test_mounted_server_does_not_have_docket
FAILED tests/server/mount/test_mount.py::TestMultipleServerMount::test_mount_with_unreachable_proxy_servers
FAILED tests/server/providers/test_local_provider.py::TestLocalProviderTaskRegistration::test_get_tasks_returns_task_eligible_tools
3 failed, 1 warning in 1.73s

…[6610 chars omitted]…
ler called: call_tool stateful_get with {}
DEBUG    fastmcp.server.providers.proxy:proxy.py:1073 <fastmcp.server.providers.proxy.StatefulProxyClient object at 0x78906d285f10> will be disconnect
=========================== short test summary info ============================
FAILED tests/server/providers/proxy/test_stateful_proxy_client.py::TestStatefulProxyClient::test_stateful_proxy
1 failed in 1.47s

                for s in spans
                if s.name.startswith("resources/read data://fail")
                and s.attributes is not None
                and "fastmcp.server.name" in s.attributes
            ),
            None,
        )
    
        # Both spans should exist
>       assert client_span is not None, "Client should create a span"
E       AssertionError: Client should create a span
E       assert None is not None

tests/client/telemetry/test_client_tracing.py:402: AssertionError
----------------------------- Captu
…[7044 chars omitted]…
resource_span_attributes
FAILED tests/client/telemetry/test_client_tracing.py::TestClientPromptTracing::test_get_prompt_span_attributes
FAILED tests/client/telemetry/test_client_tracing.py::TestClientServerSpanHierarchy::test_client_and_server_spans_created
FAILED tests/client/telemetry/test_client_tracing.py::TestClientErrorTracing::test_read_resource_error_creates_spans
11 failed, 28 passed in 2.66s

            )
            self._task_registry[server_task_id] = weakref.ref(task_obj)
            return task_obj
        else:
            # Graceful degradation - server returned GetPromptResult
            synthetic_task_id = task_id or str(uuid.uuid4())
            return PromptTask(
                self, synthetic_task_id, prompt_name=name, immediate_result=raw_result
            )

…[2090 chars omitted]…
ollowing exception:\n\nTraceback (most recent call last):\n  File "/repo/src/fastmcp/server/telemetry.py", line 94, in server_span\n    yield span\n  File "/repo/src/fastmcp/server/server.py", line 1203, in call_tool\n    raise ToolError(f"Error calling tool {name!r}: {e}") from e\nfastmcp.exceptions.ToolError: Error calling tool \'failing_tool\': Something went wrong\n', 'exception.escaped': 'False'}

-rw-r--r-- 1 root root      5 Nov  3 06:32 .python-version
lrwxrwxrwx 1 root root      9 Nov  3 06:32 AGENTS.md -> CLAUDE.md
-rw-r--r-- 1 root root  10467 Nov  3 06:32 CLAUDE.md
-rw-r--r-- 1 root root   5218 Nov  3 06:32 CODE_OF_CONDUCT.md
-rw-r--r-- 1 root root   5633 Nov  3 06:32 CONTRIBUTING.md
-rw-r--r-- 1 root root  11356 Nov  3 06:32 LICENSE
-rw-r
…[2037 chars omitted]…
apps.py
./tests/test_apps_prefab.py
./tests/test_fastmcp_app.py
./tests/test_json_schema_generation.py
./tests/test_mcp_config.py
./tests/__init__.py
./uv.lock
./v3-notes/get-methods-consolidation.md
./v3-notes/prompt-internal-types.md
./v3-notes/provider-architecture.md
./v3-notes/provider-test-pattern.md
./v3-notes/resource-internal-types.md
./v3-notes/task-meta-parameter.md
./v3-notes/visibility.md

src/fastmcp/cli/auth.py
src/fastmcp/cli/cimd.py
src/fastmcp/cli/cli.py
src/fastmcp/cli/client.py
src/fastmcp/cli/discovery.py
src/fastmcp/cli/generate.py
src/fastmcp/cli/install/__init__.py
src/fastmcp/cli/install/claude_code.py
src/fastmcp/cli/install/claude_desktop.py
src/fastmcp/cli/install/cursor.py
src/fastmcp/cli/install/gemini_cli.py
src/fastmcp/cli/install/goose.py
src/fastmcp/cli/install/mcp_json.py
src/fastmcp/cli/install/shared.py
src/fastmcp/cli/install/stdio.py
src/fastmcp/cli/run.py
src/fastmcp/cli/tasks.py
src/fastmcp/client/__init__.py
src/fas
…[8629 chars omitted]…
     if self._mask_error_details:
src/fastmcp/server/server.py:1336:                    if self._mask_error_details:
src/fastmcp/server/server.py:1434:                    if self._mask_error_details:
src/fastmcp/server/telemetry.py:76:            "rpc.system": "mcp",
src/fastmcp/server/telemetry.py:80:            "mcp.method.name": method,
src/fastmcp/settings.py:268:    mask_error_details: Annotated[

src/fastmcp/server/auth/oauth_proxy/models.py
src/fastmcp/server/auth/oauth_proxy/proxy.py
src/fastmcp/server/auth/oauth_proxy/ui.py
src/fastmcp/server/auth/oidc_proxy.py
src/fastmcp/server/auth/providers/__init__.py
src/fastmcp/server/auth/providers/auth0.py
src/fastmcp/server/auth/providers/aws.py
src/fastmcp/server/auth/providers/azure.py
src/fastmcp/server/auth/providers/clerk.py
src/fastmcp/server/auth/providers/debug.py
src/fastmcp/server/auth/p
…[8630 chars omitted]…
ver/mount/test_advanced.py:154:        """Test that custom routes from a mounted server appear in the parent.
tests/server/mount/test_advanced.py:158:        dropped when the child was mounted onto a parent, resulting in 404s.
tests/server/mount/test_advanced.py:169:        parent.mount(child)
tests/server/mount/test_advanced.py:176:    async def test_mounted_server_custom_routes_with_namespace(self):

    combined.add_provider(provider1)
    combined.add_provider(provider2, namespace="api")  # Tools become "api_foo"

    # Use like any other provider
    tools = await combined.list_tools()
    ```
"""

from __future__ import annotations

import logging
from collections.abc import AsyncIterator, Sequence
from contextlib import AsyncExitStack, asynccontextmanager
from typing import TYPE_CHECKING, TypeVar

from fastmcp.exceptions import NotFoundError
from f
…[8630 chars omitted]…
 """
        # Pass exact version so child reads the correct version
        version = VersionSpec(eq=self.version) if self.version else None

        with delegate_span(
            self._original_uri or "", "FastMCPProvider", self._original_uri or ""
        ):
            return await self._server.read_resource(
                self._original_uri, version=version, task_meta=task_meta
            )

    combined.add_provider(provider1)
    combined.add_provider(provider2, namespace="api")  # Tools become "api_foo"

    # Use like any other provider
    tools = await combined.list_tools()
    ```
"""

from __future__ import annotations

import logging
from collections.abc import AsyncIterator, Sequence
from contextlib import AsyncExitStack, asynccontextmanager
from typing import TYPE_CHECKING, TypeVar

from fastmcp.exceptions import NotFoundError
from f
…[8628 chars omitted]…
----------------
    # Lifecycle
    # -------------------------------------------------------------------------

    @asynccontextmanager
    async def lifespan(self) -> AsyncIterator[None]:
        """Combine lifespans of all providers."""
        async with AsyncExitStack() as stack:
            for p in self.providers:
                await stack.enter_async_context(p.lifespan())
            yield

    97	
    98	            provider = FastMCPProvider(provider)
    99	
   100	        # Apply namespace via wrap_transform if specified
   101	        if namespace:
   102	            provider = provider.wrap_transform(Namespace(namesp
…[8411 chars omitted]…
espacing)
939:        Protocol handlers deduplicate for MCP wire format.
978:        Extends AggregateProvider._get_prompt() with component-level auth checks.
987:        # Get prompt from AggregateProvider (handles aggregation and namespacing)
1908:    def mount(
1999:        # Use add_provider with namespace (applies namespace in AggregateProvider)
2059:        for tool in await server.list_tools():

class FastMCP(
    AggregateProvider,
    LifespanMixin,
    MCPOperationsMixin,
    TransportMixin,
    Generic[LifespanResultT],
):
    def __init__(
        self,
        name: str | None = None,
        instructions: str | None = None,
        *,
        version: str | int | float | None = None,
        website_url: str | None = None,
        icons: list[mcp.types.Icon] | None = None,
        auth: AuthProvider | None = None,
        middleware: Sequence[Middleware] | None = None,
        providers: Sequence[Provider
…[8630 chars omitted]…
   templates, and prompts are imported with their original names.

        Args:
            server: The FastMCP server to import
            prefix: Optional prefix to use for the imported server's objects. If None,
                objects are imported with their original names.
        """
        import warnings

        warnings.warn(
            "import_server is deprecated, use mount() instead",

    name: str,
    method: str,
    component_key: str,
    session_id: str | None = None,
    resource_uri: str | None = None,
) -> Generator[Span, None, None]:
    """Create a CLIENT span with standard MCP attributes.

    Automatically records any exception on the span and sets error status.
    """
    tracer = get_tracer()
    with tracer.start_as_current_span(name, kind=SpanKind.CLIENT) as span:
        attrs: dict[str, str] = {
            # RPC semantic conventions
            "rpc.system": "mcp",
            "rpc.method": method,
            # MCP semantic conventions
            "mcp.method.name": method,
            # F
…[6644 chars omitted]…
mcp/telemetry.py:27:from opentelemetry import propagate, trace
src/fastmcp/telemetry.py:28:from opentelemetry.context import Context
src/fastmcp/telemetry.py:29:from opentelemetry.trace import Span, Status, StatusCode, Tracer
src/fastmcp/telemetry.py:30:from opentelemetry.trace import get_tracer as otel_get_tracer
src/fastmcp/utilities/components.py:251:        """Return span attributes for telemetry.

    import datetime

    from fastmcp.client.client import CallToolResult, Client
from fastmcp.client.progress import ProgressHandler
from fastmcp.client.tasks import ToolTask
from fastmcp.client.telemetry import client_span
from fastmcp.exceptions import ToolError
from fastmcp.telemetry import inject_trace_context
from fastmcp.utilities.json_schema_type import json_schema_to_type
from fastmcp.utilities.logging import get_logger
from fastmcp.utilities.timeout import normalize_timeout_to_timedelta
from fastmcp.utilities.types import get_cached_typeadapter

logger = get_logger(__name__)

AUTO_PAGINATION_MAX_PAGES = 250

# Type alias for task response unio
…[8630 chars omitted]…
y[server_task_id] = weakref.ref(task_obj)
            return task_obj
        else:
            # Graceful degradation - server returned ReadResourceResult
            synthetic_task_id = task_id or str(uuid.uuid4())
            return ResourceTask(
                self,
                synthetic_task_id,
                uri=str(uri),
                immediate_result=raw_result.contents,
            )

   107	        return all_tools
   108	
   109	    # --- Call Tool ---
   110	
   111	    async def call_tool_mcp(
   112	        self: Client,
   113	        name: str,
   114	        arguments: dict[str, Any],
   115	        progress_handler: ProgressHandler | None = None,
   116	        timeout: datetime.timedelta | float | int | None = None,
   117	        meta: dict[str, Any] | Non
…[8630 chars omitted]…
est_meta.get("fastmcp", {}),
   290	                "version": version,
   291	            }
   292	
   293	        if task:
   294	            return await self._read_resource_as_task(
   295	                uri, task_id, ttl, meta=request_meta or None
   296	            )
   297	
   298	        if isinstance(uri, str):
   299	            try:
   300	                uri = AnyUrl(uri)  # Ensure AnyUrl

   197	        timeout: datetime.timedelta | float | int | None = None,
   198	        progress_handler: ProgressHandler | None = None,
   199	        raise_on_error: bool = True,
   200	        meta: dict[str, Any] | None = None,
   201	        task: Literal[False] = False,
   202	    ) -> CallToolResult: ...
   203	
   204	    @overload
   205	    async def call_tool(
   206	        self: Client,
   207	        name: str,
   208	        arguments: dict[str, Any] | None = None,
   209	      
…[8630 chars omitted]…
5	        uri: AnyUrl | str,
   236	        *,
   237	        version: str | None = None,
   238	        meta: dict[str, Any] | None = None,
   239	        task: Literal[False] = False,
   240	    ) -> list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents]: ...
   241	
   242	    @overload
   243	    async def read_resource(
   244	        self: Client,
   245	        uri: AnyUrl | str,

   272	                "version": version,
   273	            }
   274	
   275	        if task:
   276	            return await self._call_tool_as_task(
   277	                name, arguments, task_id, ttl, meta=request_meta or None
   278	            )
   279	
   280	        result = await 
…[8629 chars omitted]…
te_result=None
            )
            self._task_registry[server_task_id] = weakref.ref(task_obj)
            return task_obj
        else:
            # Graceful degradation - server returned GetPromptResult
            synthetic_task_id = task_id or str(uuid.uuid4())
            return PromptTask(
                self, synthetic_task_id, prompt_name=name, immediate_result=raw_result
            )

    13	if TYPE_CHECKING:
    14	    from fastmcp.client.client import Client
    15	
    16	from fastmcp.client.tasks import PromptTask
    17	from fastmcp.client.telemetry import client_span
    18	from fastmcp.telemetry import inject_trace_context
    19	from fastmcp.utilities.logging import get_logger
    20	
    21	logger = get_logger(__name__)
    22	
    23	AUTO_PAGINATION_MAX_PAGES = 250
    24	
    25	# Type alias for task response union (SEP-1686 graceful degradation)
    26	PromptTaskResponseUnion = RootModel[
    27	    mcp.types.CreateTaskResult | mcp.ty
…[8630 chars omitted]…
   236	        *,
   237	        version: str | None = None,
   238	        meta: dict[str, Any] | None = None,
   239	        task: Literal[False] = False,
   240	    ) -> list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents]: ...
74:from fastmcp.server.telemetry import server_span
1136:            with server_span(
1265:            with server_span(
1418:            with server_span(

  1092	            version: Specific version to call. If None, calls highest version.
  1093	            run_middleware: If True (default), apply the middleware chain.
  1094	                Set to False when called from middleware to avoid re-applying.
  1095	            task_meta: If provided, execute as a background task and return
  1096	                CreateTaskResult. If None (default), execute synchro
…[8630 chars omitted]…
- key format is "tool:name@version"
            key = f"{Tool.make_key(name)}@{version}"
            if key not in self._components:
                raise KeyError(f"Tool {name!r} version {version!r} not found")
            self._remove_component(key)

    def remove_resource(self, uri: str, version: str | None = None) -> None:
        """Remove resource(s) from this provider's storage.

        Args:

  1132	                )
  1133	
  1134	            # Core logic: find and execute tool (providers queried in parallel)
  1135	            # Use get_tool to apply transforms and filter disabled
  1136	            with server_span(
  1137	                f"tools/call {name}", "tools/call", self.name, "
…[8630 chars omitted]…
  2015	        Note that when a server is *imported*, its objects are immediately
  2016	        registered to the importing server. This is a one-time operation and
  2017	        future changes to the imported server will not be reflected in the
  2018	        importing server. Server-level configurations and lifespans are not imported.
  2019	
  2020	        When a server is imported with a prefix:

tests/server/auth/providers/test_github.py
tests/server/auth/providers/test_google.py
tests/server/auth/providers/test_http_client.py
tests/server/auth/providers/test_introspection.py
tests/server/auth/providers/test_propelauth.py
tests/server/auth/providers/test_scalekit.py
tests/server/auth/providers/test_supabase.py
tests/server/auth/providers/test_workos.py
tests/server/auth/
…[8629 chars omitted]…
 collide after sanitization get deduplicated."""
tests/utilities/test_components.py:172:        """Test that tags are deduplicated when passed as a sequence."""
tests/utilities/test_logging.py:35:    """Test that traceback-related kwargs can be passed without causing duplicate argument errors."""
tests/utilities/test_logging.py:36:    # This should not raise TypeError about duplicate keyword arguments

@provider.tool
def greet(name: str) -> str:
    return f"Hello, {name}!"

# Attach to any server
from fastmcp import FastMCP
server1 = FastMCP("Server1", providers=[provider])
server2 = FastMCP("Server2", providers=[provider])
```
"""

from __future__ import annotations

from collections.abc import Sequence
from typing import Literal, TypeVar

from fastmcp.prompts.base import Prompt
from fastmcp.resources.base import Resource
from fastmcp.resources.template import ResourceTemplate
from fas
…[8629 chars omitted]…
haviorSetting
src/fastmcp/server/server.py:119:DuplicateBehavior = Literal["warn", "error", "replace", "ignore"]
src/fastmcp/server/server.py:275:        on_duplicate: DuplicateBehavior | None = None,
src/fastmcp/server/server.py:292:        self._on_duplicate: DuplicateBehaviorSetting = on_duplicate or "warn"
src/fastmcp/settings.py:28:DuplicateBehavior = Literal["warn", "error", "replace", "ignore"]

class TestClientToolTracing:
    """Tests for client tool call tracing."""

    async def test_call_tool_creates_span(self, trace_exporter: InMemorySpanExporter):
        server = FastMCP("test-server")

        @server.tool()
        def greet(name: str) -> str:
            return f"Hello, {name}!"

        client = Client(server)
        async with client:
            result = await client.call_tool("greet", {"name": "World"})
            assert "Hello, World!" in str(result)

        spans = trace_exporter.get_finished_spans()
…[8630 chars omitted]…
ultiple mounted servers fail to connect."""
        caplog.set_level(logging.DEBUG, logger="fastmcp")

        main_app = FastMCP("MainApp")
        working_app = FastMCP("WorkingApp")

        @working_app.tool
        def working_tool() -> str:
            return "Working tool"

        @working_app.resource(uri="working://data")
        def working_resource():
            return "Working resource"

   462	
   463	        Args:
   464	            provider: A Provider instance that will provide components dynamically.
   465	            namespace: Optional namespace prefix. When set:
   466	                - Tools become "namespace_toolname"
   467	           
…[8630 chars omitted]…
_tools(self) -> list[Tool]:
src/fastmcp/server/providers/base.py:136:    async def list_tools(self) -> Sequence[Tool]:
src/fastmcp/server/providers/base.py:204:    async def list_resources(self) -> Sequence[Resource]:
src/fastmcp/server/providers/base.py:276:    async def list_prompts(self) -> Sequence[Prompt]:
src/fastmcp/server/providers/base.py:315:    async def _list_tools(self) -> Sequence[Tool]:

   662	            return None
   663	
   664	        all_tools = [t for t in await super().list_tools() if t.name == name]
   665	        all_tools = list(await apply_session_transforms(all_tools))
   666	        enabled = [t for t in all_tools if is_enabled(t) and _is_model_visible(t)]
   667	
   668	        skip_auth
…[8630 chars omitted]…
 """
        # Pass exact version so child reads the correct version
        version = VersionSpec(eq=self.version) if self.version else None

        with delegate_span(
            self._original_uri or "", "FastMCPProvider", self._original_uri or ""
        ):
            return await self._server.read_resource(
                self._original_uri, version=version, task_meta=task_meta
            )

if TYPE_CHECKING:
    from docket import Docket
    from docket.execution import Execution

T = TypeVar("T", default=Any)


class FastMCPMeta(TypedDict, total=False):
    tags: list[str]
    version: str
    versions: list[str]


def get_fastmcp_metadata(meta: dict[str, Any] | None) -> FastMCPMeta:
    """Extract FastMCP metadata from a component's meta dict.

    Handles both the current `fastmcp` namespace and the legacy `_fastmcp`
    namespace for compatibility with older FastMCP servers.
    """
    if not meta:
   
…[8630 chars omitted]…
erver/middleware/test_error_handling.py:548:                await client.call_tool("failing_operation", {"error_type": "value"})
tests/server/middleware/test_error_handling.py:605:                await client.call_tool("failing_operation", {"error_type": "value"})
tests/server/middleware/test_error_handling.py:633:                    await client.call_tool("failing_operation", {"error_type": "value"})

class NotFoundError(Exception):
    """Object not found."""


class DisabledError(Exception):
    """Object is disabled."""


class AuthorizationError(FastMCPError):
    """Error when authorization check fails."""
1136:            with server_span(
1265:            with server_span(
1418:            with server_span(

    13	    Callable,
    14	    Sequence,
    15	)
    16	from contextlib import (
    17	    AbstractAsyncContextManager,
    18	    asynccontextmanager,
    19	)
    20	from dataclasses import replace
    21	from functools import partial
    22	from pathlib import Path
    23	from typing import TYPE_CHECKING, Any, Generic, Literal, TypeVar, cast, overload
    24	
    25	import httpx
    26	import mcp.types
    27	from key_value.aio.adapters.pydantic import PydanticAdapter
    28	from key_value.aio.protocols import AsyncKeyValue
    29	from key_value.aio.stores.memory impor
…[8629 chars omitted]…
t (
        BlobResourceContents,
        EmbeddedResource,
        ImageContent,
        TextContent,
    )
    from pydantic import AnyUrl

    from fastmcp import FastMCP
    from fastmcp.utilities.types import Audio, File, Image

    mcp = FastMCP()

    @mcp.tool
    def add(x: int, y: int) -> int:
        return x + y

    @mcp.tool
    def list_tool() -> list[str | int]:
        return ["x", 2]

tests/client/telemetry/test_client_tracing.py:609:        server_span = next(
tests/client/telemetry/test_client_tracing.py:622:        assert server_span is not None
tests/client/telemetry/test_client_tracing.py:623:        assert server_span.attributes is not None
tests/client/telemetry/test_client_tracing.py:627:        server_session = server_span.attributes.get("mcp.session.id")

  1212	        run_middleware: bool = True,
  1213	        task_meta: TaskMeta | None = None,
  1214	    ) -> ResourceResult | mcp.types.CreateTaskResult:
  1215	        """Read a resource by URI.
  1216	
  1217	        This is the public API for reading resources. By default, middleware is applied.
  1218	        Checks concrete resources first, then templates.
  1219	
  1220	        Args:
  1221	            uri: The resource URI
  1222	            version: Specific version to read. If None, reads highest vers
…[8630 chars omitted]…
utilities.tests import run_server_async
   509	
   510	        server = FastMCP("session-test-server")
   511	
   512	        @server.tool()
   513	        def echo(message: str) -> str:
   514	            return message
   515	
   516	        async with run_server_async(server) as url:
   517	            yield url
   518	
   519	    async def test_client_span_includes_session_id(
   520	        self,

  1270	                uri,
  1271	                resource_uri=uri,
  1272	            ) as span:
  1273	                # Try concrete resources first (transforms + auth via _get_resource)
  1274	                resource = await self.get_resource(uri, version=version)
  1275	                if resource is not None:
  1276	                    span.set_attributes(resource.get_span_attributes())

…[8630 chars omitted]…

        assert len(spans) == 1

        span = spans[0]
        assert span.attributes is not None
        assert span.attributes["enduser.id"] == "test-client-123"
        assert span.attributes["enduser.scope"] == "read write"

    async def test_resource_span_includes_auth_attributes_when_authenticated(
        self, trace_exporter: InMemorySpanExporter
    ):
        mcp = FastMCP("test-server")

</ParamField>

<ParamField body="strict_input_validation" type="bool" default="False">
  <VersionBadge version="2.13.0" />

  When `False` (default), FastMCP uses Pydantic's flexible validation that coerces compatible inputs (e.g., `"10"` → `10` for int parameters). When `True`, validates inputs against the exact JSON Schema before calling your function, rejecting type mismatches. See [Input V
…[5082 chars omitted]…
s": "Use `on_duplicate=` instead.",
src/fastmcp/server/server.py:134:    "on_duplicate_prompts": "Use `on_duplicate=` instead.",
src/fastmcp/server/server.py:275:        on_duplicate: DuplicateBehavior | None = None,
src/fastmcp/server/server.py:292:        self._on_duplicate: DuplicateBehaviorSetting = on_duplicate or "warn"
src/fastmcp/server/server.py:313:            on_duplicate=self._on_duplicate

ase.py:143:    KEY_PREFIX: ClassVar[str] = "tool"
src/fastmcp/prompts/base.py:201:    KEY_PREFIX: ClassVar[str] = "prompt"
src/fastmcp/resources/base.py:214:    KEY_PREFIX: ClassVar[str] = "resource"
src/fastmcp/resources/base.py:398:    def key(self) -> str:
src/fastmcp/resources/template.py:115:    KEY_PREFIX: ClassVar[str] = "template"
src/fastmcp/resources/template.py:296:    def key(self) -> str:

        result: Raw MCP protocol result
        tool_output_schemas: Dictionary mapping tool names to their output schemas
        list_tools_fn: Async function to refresh tool schemas if needed
        client_name: Optional client name for logging
        raise_on_error: Whether to raise ToolError on errors

    Returns:
        CallToolResult: Parsed result with structured data
    """
    # Local import: CallToolResult is under TYPE_CHECKING at module level to
  
…[8630 chars omitted]…
ol = False,
        stateless: bool = False,
    ):
        """
        Overrides the run method to use the MiddlewareServerSession.
        """
        async with AsyncExitStack() as stack:
            lifespan_context = await stack.enter_async_context(self.lifespan(self))
            session = await stack.enter_async_context(
                MiddlewareServerSession(
                    self.fastmcp,

    Literal,
    Protocol,
    TypeVar,
    overload,
    runtime_checkable,
)

import anyio
from mcp.shared.exceptions import McpError
from mcp.types import ErrorData, Icon, ToolAnnotations
from pydantic import Field
from pydantic.json_schema import SkipJsonSchema

import fastmcp
from fastmcp.decorators import resolve_task_config
from fastmcp.exceptions import FastMCPDeprecationWarning
from fastmcp.server.auth.authorization import AuthCheck
from fastmcp.server.dependencies import without_injected_parameters
from fastmcp.server.tasks.config import TaskConfig
from fastmcp.tools.base import (
    Tool,
    ToolResult,
    ToolResultSer
…[8630 chars omitted]…
equest",
                    method="prompts/get",
                    fastmcp_context=ctx,
                )
                return await self._run_middleware(
                    context=mw_context,
                    call_next=lambda context: self.render_prompt(
                        context.message.name,
                        context.message.arguments,
                        version=version,

  1407	                    call_next=lambda context: self.render_prompt(
  1408	                        context.message.name,
  1409	                        context.message.arguments,
  1410	                        version=version,
  1411	                        run_middleware=False,
  1412	                        task_meta=tas
…[8630 chars omitted]…
 153	
   154	        This is called when the tool is used within a TransformedTool
   155	        forwarding function or other contexts where task_meta is not available.
   156	        """
   157	        # Pass exact version so child executes the correct version
   158	        version = VersionSpec(eq=self.version) if self.version else None
   159	
   160	        result = await self._server.call_tool(

from collections.abc import Awaitable, Callable, Sequence
from typing import TYPE_CHECKING, Any, cast
from urllib.parse import quote

import mcp.types
from mcp import ServerSession
from mcp.client.session import ClientSession
from mcp.server.lowlevel.server import request_ctx
from mcp.shared.context import LifespanContextT, RequestContext
from mcp.shared.exceptions import McpError
from mcp.types import (
    METHOD_NOT_FOUND,
    BlobResourceContents,
    ElicitRequestFormParams,
    TextResourceContents,
)
from pydantic.networks import AnyUrl

from fast
…[8629 chars omitted]…
server/server.py:1136:            with server_span(
src/fastmcp/server/server.py:1265:            with server_span(
src/fastmcp/server/server.py:1418:            with server_span(
src/fastmcp/server/telemetry.py:56:def server_span(
246:                result = await client.read_resource(backend_uri)
345:            result = await client.read_resource(parameterized_uri)
805:class FastMCPProxy(FastMCP):

   112	        )
   113	
   114	    async def run(
   115	        self,
   116	        arguments: dict[str, Any],
   117	        context: Context | None = None,
   118	    ) -> ToolResult:
   119	        """Executes the tool by making a call through the client."""
   120	        backend_name = self._backend_name or sel
…[8630 chars omitted]…
try/test_server_tracing.py:31:        assert span.name == "tools/call greet"
tests/server/telemetry/test_server_tracing.py:35:        assert span.attributes["mcp.method.name"] == "tools/call"
tests/server/telemetry/test_server_tracing.py:39:        assert span.attributes["rpc.method"] == "tools/call"
tests/server/telemetry/test_server_tracing.py:61:        assert span.name == "tools/call failing_tool"

    task_config: TaskConfig = TaskConfig(mode="optional")
    parameters: dict[str, Any] = {"type": "object", "properties": {}}

    async def run(self, arguments: dict[str, Any]) -> ToolResult:
        return ToolResult(content="custom result")


class SimpleProvider(Provider):
    """Minimal provider that returns custom components from list methods."""

    def __init__(self, tools: list[Tool] | None = None):
        super().__init__()
        self._tools = tools or []

    async def _list_tools(self) -> list[Tool]:
      
…[8629 chars omitted]…
p(
        self, base_server: FastMCP, dynamic_tools: list[Tool]
    ):
        """Test that call_tool uses get_tool() for efficient single-tool lookup."""
        provider = SimpleToolProvider(tools=dynamic_tools)
        base_server.add_provider(provider)

        await base_server.call_tool(name="dynamic_multiply", arguments={"a": 2, "b": 3})

        # get_tool is called once for efficient lookup:

from fastmcp.server.providers.base import Provider
from fastmcp.utilities.versions import VersionSpec

if TYPE_CHECKING:
    from fastmcp.prompts.base import Prompt
    from fastmcp.resources.base import Resource
    from fastmcp.resources.template import ResourceTemplate
    from fastmcp.server.transforms import Transform
    from fastmcp.tools.base import Tool
    from fastmcp.utilities.components import FastMCPComponent


clas
…[8630 chars omitted]…
sses can override this to customize task routing behavior.
363-        For example, FastMCPProviderTool overrides to delegate to child
364-        middleware without submitting to Docket.
365-        """
366-        from fastmcp.server.tasks.routing import check_background_task
367-
368-        task_result = await check_background_task(
369-            component=self,
370-            task_type="tool",

494:class FastMCPProvider(Provider):
640:    # Prompt methods
643:    async def _list_prompts(self) -> Sequence[Prompt]:
644:        """List all prompts
…[8629 chars omitted]…
ror rendering prompt {name!r}")
  1434	                    if self._mask_error_details:
  1435	                        raise PromptError(f"Error rendering prompt {name!r}") from e
  1436	                    raise PromptError(f"Error rendering prompt {name!r}: {e}") from e
  1437	
  1438	    def add_tool(self, tool: Tool | Callable[..., Any]) -> Tool:
  1439	        """Add a tool to the server.
  1440

   182	    """
   183	
   184	    _server: Any = None  # FastMCP, but Any to avoid circular import
   185	    _original_uri: str | None = None
   186	
   187	    def __init__(
   188	        self,
   189	        server: Any,
   190	        original_uri: str,
   191	        **kwargs: Any,
   192	    ):
…[8630 chars omitted]…
------------
    # Tools
    # -------------------------------------------------------------------------

    async def _list_tools(self) -> Sequence[Tool]:
        """List all tools from all providers."""
        results = await gather(
            *[p.list_tools() for p in self.providers],
            return_exceptions=True,
        )
        return self._collect_list_results(results, "list_tools")

    GetToolNext,
    Transform,
)
from fastmcp.utilities.versions import VersionSpec

if TYPE_CHECKING:
    from fastmcp.prompts.base import Prompt
    from fastmcp.resources.base import Resource
    from fastmcp.resources.template import ResourceTemplate
    from fastmcp.tools.base import Tool

# Pattern for matching URIs: protocol://path
_URI_PATTERN = re.compile(r"^([^:]+://)(.*?)$")


class Namespace(Transform):
    """Prefixes component names with a namespace.

    - Tools: name → namespace_name
    - Prompts: name → namespace_name
    - Resources: protocol://path → protocol://namespace/path
    - Res
…[8629 chars omitted]…
ributes:
        parent_tool: The original tool that this tool was transformed from.
        fn: The function to execute when this tool is called (either the forwarding
            function for pure transformations or a custom user function).
        forwarding_fn: Internal function that handles argument transformation and
            validation when forward() is called from custom functions.
    """

147-        tools = await self._list_tools()
148-        for transform in self.transforms:
149-            tools = await transform.list_tools(tools)
150-        return tools
151-
152-    async def get_tool(
153-        self, name: str, version: VersionSpec | None = None
154-    ) -> Tool | None:
155-        """Ge
…[8628 chars omitted]…
turn FastMCPProviderPrompt.wrap(self.server, raw_prompt)
666-
667-    # -------------------------------------------------------------------------
668-    # Task registration
669-    # -------------------------------------------------------------------------
670-
671-    async def get_tasks(self) -> Sequence[FastMCPComponent]:
672-        """Return task-eligible components from the mounted server.
673-

   358	        self,
   359	        server: Any,
   360	        original_uri_template: str,
   361	        **kwargs: Any,
   362	    ):
   363	        super().__init__(**kwargs)
   364	        self._server = server
   365	        self._original_uri_template = original_uri_template
   366	
   367	    @classmethod
   368	    def wrap(
   369	        cls, server: Any, template: ResourceTempla
…[8629 chars omitted]…
pstream request timed out, please retry"
  1334	                        ) from e
  1335	                    # Standard masking logic
  1336	                    if self._mask_error_details:
  1337	                        raise ResourceError(f"Error reading resource {uri!r}") from e
  1338	                    raise ResourceError(f"Error reading resource {uri!r}: {e}") from e
  1339	
  1340	    @overload

def get_logger(name: str) -> logging.Logger:
    """Get a logger nested under FastMCP namespace.

    Args:
        name: the name of the logger, which will be prefixed with 'FastMCP.'

    Returns:
        a configured logger instance
    """
    if name.startswith("fastmcp."):
        return logging.getLogger(name=name)

    return logging.getLogger(name=f"fastmcp.{name}")


def configure_logging(
    level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] | int = "INFO",
    logger: logging.Logger | None = None,
    enable_rich_tracebacks: bool | None = None,
    **rich_kwargs: Any,
) -> None:
    """
    Configure logging for FastMCP.

    
…[6694 chars omitted]…
33:        mcp = FastMCP("TestServer", mask_error_details=True)
tests/client/client/test_error_handling.py:49:        mcp = FastMCP("TestServer", mask_error_details=True)
tests/client/client/test_error_handling.py:95:        mcp = FastMCP("TestServer", mask_error_details=True)
tests/client/client/test_error_handling.py:141:        mcp = FastMCP("TestServer", mask_error_details=True)
254:class FastMCP(

133-                    client._proxy_rc_ref[0] = (
134-                        ctx.request_context,
135-                        ctx._fastmcp,  # weakref to FastMCP, not the Context
136
…[8629 chars omitted]…
c/fastmcp/client/mixins/prompts.py:107:    async def get_prompt_mcp(
src/fastmcp/client/mixins/resources.py:177:    async def read_resource_mcp(
src/fastmcp/client/mixins/tools.py:111:    async def call_tool_mcp(
src/fastmcp/client/mixins/tools.py:191:    async def call_tool(
src/fastmcp/client/mixins/tools.py:205:    async def call_tool(
src/fastmcp/client/mixins/tools.py:220:    async def call_tool(

    62	ToolResultSerializerType: TypeAlias = Callable[[Any], str]
    63	
    64	
    65	def default_serializer(data: Any) -> str:
    66	    return pydantic_core.to_json(data, fallback=str).decode()
    67	
    68	
    69	class ToolResult(BaseModel):
    70	    content: list[ContentBlock] = Field(
    71	        description="List of content blocks for the tool result"
    72	    )
    73	    structured_content: dict[str, Any] | None = Field(
    74	        default=None, description="Structured content matching 
…[7989 chars omitted]…
ns the raw CallToolResult object, which includes an isError flag
src/fastmcp/client/mixins/tools.py:388:    if result.isError and raise_on_error:
src/fastmcp/client/mixins/tools.py:394:    elif result.structuredContent and not result.isError:
src/fastmcp/client/mixins/tools.py:443:        is_error=result.isError,
1055:    async def call_tool(
1066:    async def call_tool(
1076:    async def call_tool(

   562	        Overrides Provider.list_tools() to add visibility filtering, auth filtering,
   563	        and middleware execution. Returns all versions (no deduplication).
   564	        Protocol handlers deduplicate for MCP wire format.
   565	        """
   566	        async with fastmcp.server.context
…[8556 chars omitted]…
--------------------------------------
    # Internal transform chain building
    # -------------------------------------------------------------------------

    async def list_tools(self) -> Sequence[Tool]:
        """List tools with all transforms applied.

        Applies transforms sequentially: base → transforms (in order).
        Each transform receives the result from the previous transform.

class TestErrorHandling:
    async def test_general_tool_exceptions_are_not_masked_by_default(self):
        mcp = FastMCP("TestServer")

        @mcp.tool
        def error_tool():
            raise ValueError("This is a test error (abc)")

        client = Client(transport=FastMCPTransport(mcp))

        async with client:
            result = await client.call_tool_mcp("error_tool", {})
            assert result.isError
            assert isinstance(result.content[0], TextContent)
            assert "test 
…[8629 chars omitted]…
mpt(
        self,
        name: str,
        arguments: dict[str, Any] | None = None,
        *,
        version: VersionSpec | None = None,
        run_middleware: bool = True,
        task_meta: None = None,
    ) -> PromptResult: ...

1281:                    except (FastMCPError, McpError):
1320:                except (FastMCPError, McpError):
1429:                except (FastMCPError, McpError):

   222	
   223	        No-ops if task_config.mode is "forbidden". Subclasses override to
   224	        register their callable (self.run, self.read, self.render, or self.fn).
   225	        """
   226	        # Base implementation: no-op (subclasses override)
   
…[8629 chars omitted]…
rrent()
   112	
   113	
   114	__all__ = [
   115	    "INSTRUMENTATION_NAME",
   116	    "TRACE_PARENT_KEY",
   117	    "TRACE_STATE_KEY",
   118	    "extract_trace_context",
   119	    "get_tracer",
   120	    "inject_trace_context",
   121	    "record_span_error",
   122	]
12:    "opentelemetry-api>=1.20.0",
70:    "opentelemetry-sdk>=1.20.0",
91:    "opentelemetry-exporter-otlp-proto-grpc>=1.39.0",

   502	    classes that delegate execution to the wrapped server's middleware chain.
   503	    This ensures middleware runs when components are executed.
   504	
   505	    Example:
   506	        ```python
   507	        from fastmcp import FastMCP
   508	        from fastmcp.server.providers import FastMCPProvider
   509	
   510	        main = FastMCP("Main")
   511	        sub = FastMCP("Su
…[8630 chars omitted]…
tr, Any]:
   331	        return super().get_span_attributes() | {
   332	            "fastmcp.component.type": "resource_template",
   333	            "fastmcp.provider.type": "LocalProvider",
   334	        }
   335	
   336	
   337	class FunctionResourceTemplate(ResourceTemplate):
   338	    """A template for dynamically creating resources."""
   339	
   340	    fn: SkipJsonSchema[Callable[..., Any]]

src/fastmcp/utilities/components.py:250:    def get_span_attributes(self) -> dict[str, Any]:

   452	        if isinstance(fmeta, ToolMeta):
   453	            return FunctionTool.from_function(tool, metadata=fmeta)
   454	
   455	        return cls.from_function(tool)
   456	
   457	    def get_span_attributes(self) -> dict[str, Any]:
   458	        return super().get_span_attributes() | {
   459	            "fastmcp.component.type": "tool",
   460	            "fastmcp.provider.type": "LocalProvi
…[2334 chars omitted]…
_attributes() | {
   432	            "fastmcp.component.type": "resource",
   433	            "fastmcp.provider.type": "LocalProvider",
   434	        }
   435	
   436	
   437	__all__ = [
   438	    "Resource",
   439	    "ResourceContent",
   440	    "ResourceResult",
   441	]
   442	
   443	
   444	def __getattr__(name: str) -> Any:
   445	    """Deprecated re-exports for backwards compatibility."""

src/fastmcp/server/transforms/resources_as_tools.py:150:            result = await ctx.fastmcp.read_resource(uri)
src/fastmcp/server/transforms/search/base.py:242:            return await ctx.fastmcp.call_tool(name, arguments)
261:    def read_resource(

from fastmcp.exceptions import DisabledError, NotFoundError
from fastmcp.server.tasks.config import TaskMeta
from fastmcp.utilities.logging import get_logger
from fastmcp.utilities.pagination import paginate_sequence
from fastmcp.utilities.versions import VersionSpec, dedupe_with_versions

if TYPE_CHECKING:
    from fastmcp.server.server import FastMCP

logger = get_logger(__name__)

PaginateT = TypeVar("PaginateT")


def _apply_pagination(
    items: Sequence[PaginateT],
    cursor: str | None,
    page_size: int | None,
) -> tuple[list[Pa
…[8629 chars omitted]…
s.CreateTaskResult],
        ]:
            async def handler(
                req: mcp.types.GetPromptRequest,
            ) -> mcp.types.ServerResult:
                result = await func(req.params.name, req.params.arguments)
                return mcp.types.ServerResult(result)

            self.request_handlers[mcp.types.GetPromptRequest] = handler
            return func

        return decorator

   112	
   113	        # SDK may pass None for internal cache refresh despite type hint
   114	        cursor = (
   115	            request.params.cursor if request is not None a
…[8630 chars omitted]…
   242	                    write_stream,
   243	                    initialization_options,
   244	                    stateless=stateless,
   245	                )
   246	            )
   247	
   248	            async with anyio.create_task_group() as tg:
   249	                # Store task group on session for subscription tasks (SEP-1686)
   250	                session._subscription_task_group = tg

   200	        to call_tool(). The tool's _run() method handles the backgrounding decision,
   201	        ensuring middleware runs before Docket.
   202	
   203	        Args:
   204	            key: The name of the tool to call
   205	            arguments: Arguments to pass to the tool
   206	
   207	        Returns:
   208	            Tool result or CreateTaskResult for background execution
   209	        """
   210	       
…[7650 chars omitted]…
"FastMCP", self)
   366	        logger.debug(f"[{server.name}] Handler called: set_logging_level %s", level)
   367	        try:
   368	            ctx = server._mcp_server.request_context
   369	            session = ctx.session
   370	            if isinstance(session, MiddlewareServerSession):
188:    async def _call_tool_mcp(
248:    async def _read_resource_mcp(
304:    async def _get_prompt_mcp(

from fastmcp.utilities.versions import (
    VersionKey,
    compare_versions,
    is_version_greater,
)


class TestVersionKey:
    """Tests for VersionKey comparison class."""

    def test_none_sorts_lowest(self):
        """None (unversioned) should sort lower than any version."""
        assert VersionKey(None) < VersionKey("1.0")
        assert VersionKey(None) < VersionKey("0.1")
        assert VersionKey(None) < VersionKey("anything")

    def test_none_equals_none(self):
        """Two None versions should be equal."""
        assert VersionKey(None) == Versio
…[8629 chars omitted]…
              update={
323-                    "meta": {
324-                        **meta,
325-                        "fastmcp": {
326-                            **meta.get("fastmcp", {}),
327-                            "versions": all_versions,
328-                        },
329-                    }
330-                }
331-            )
332-        result.append(highest)
333-    return result

   365	        if tools:
   366	            for tool in tools:
   367	                if not isinstance(tool, Tool):
   368	                    tool = Tool.from_function(tool)
   369	                self.add_tool(tool)
   370	
   371	        self.strict_input_validation: bool = (
   372	
…[3012 chars omitted]…
 self._mcp_server: LowLevelServer[LifespanResultT, Any] = LowLevelServer[
405:        return self._mcp_server.name
409:        return self._mcp_server.instructions
413:        self._mcp_server.instructions = value
417:        return self._mcp_server.version
421:        return self._mcp_server.website_url
425:        if self._mcp_server.icons is None:
428:            return list(self._mcp_server.icons)

50-
51:async def gather(
52-    *awaitables: Awaitable[T],
53-    return_exceptions: bool = False,
54-) -> list[T] | list[T | BaseException]:
55-    """Run awaitables concurrently and return results in order.
56-
57-    Uses anyio TaskGroup for structured concurrency.
58-
59-    Args:
60-        *awaitables: Awaitables to run concurrently
61-        return_exceptions: If True, exceptions are returned in results.
62-                          If False, first exception cancels all and raises.
63-
64-    Returns:
65-        List of results in the same order as input awaitables.
66-    """
67-    results: list[T 
…[8629 chars omitted]…
tr):
    """Lazy import for providers to avoid circular imports."""
    if name == "ProxyProvider":
        from fastmcp.server.providers.proxy import ProxyProvider

        return ProxyProvider
    if name == "OpenAPIProvider":
        from fastmcp.server.providers.openapi import OpenAPIProvider

        return OpenAPIProvider
    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

…[7193 chars omitted]…
ool
    return await call_next(context)
           ^^^^^^^^^^^^^^^^^^^^^^^^
  File "/repo/src/fastmcp/server/server.py", line 1185, in call_tool
    raise ToolError(f"Error calling tool {name!r}: {e}") from e
fastmcp.exceptions.ToolError: Error calling tool 'fail': SECRET
duplicate list: ['api_same', 'api_same']
masked parent error: ToolError Error calling tool 'fail': SECRET
child mask remains: False

    28	            )
    29	        })
    30	        ```
    31	    """
    32	
    33	    def __init__(self, transforms: dict[str, ToolTransformConfig]) -> None:
    34	        """Initialize ToolTransform.
    35	
    36	        Args:
    37	            transforms: Map of original tool name → transform config.
    38	        """
    39	        self
…[2425 chars omitted]…
	            # Only return if requested name matches transformed name
    91	            if transformed.name == name:
    92	                return transformed
    93	            return None
    94	
    95	        # No transform, return as-is only if name matches
    96	        return tool if tool.name == name else None
src/fastmcp/tools/base.py:457:    def get_span_attributes(self) -> dict[str, Any]:

…[8649 chars omitted]…
ount(first_app, "api")
421:        main_app.mount(second_app, "api")
447:        main_app.mount(first_app)
448:        main_app.mount(second_app)
474:        main_app.mount(first_app, "api")
475:        main_app.mount(second_app, "api")
501:        main_app.mount(first_app)
502:        main_app.mount(second_app)
530:        main_app.mount(first_app, "api")
531:        main_app.mount(second_app, "api")

   122	            assert "This is a resource error (xyz)" in str(excinfo.value)
   123	
   124	    async def test_general_template_exceptions_are_not_masked_by_default(self):
   125	        mcp = FastMCP("TestServer")
   126	
   127	        @mcp.resource(uri="exception://resource/{id}")
   128	        async def exception_resource(id: str):
   129	      
…[5818 chars omitted]…
 await _parse_call_tool_result(
   258	            name="my_tool",
   259	            result=result,
   260	            tool_output_schemas={},
   261	            list_tools_fn=None,
   262	            raise_on_error=False,
   263	        )
   264	
   265	        assert parsed.is_error is True
   266	        assert parsed.data is None
   267	        assert parsed.structured_content == {"key": "value"}

973-
974-        # Set visibility metadata if enabled was explicitly provided.
975-        # This allows enabled=True to override an earlier disable (later transforms win).
976-        if "enabled" in self.model_fields_set:
977-            _set_visibility_metadata(transformed, enabled=self.enabled)
978-
979-        return transformed
980-
981-
982:def apply_transf
…[8628 chars omitted]…
  Returns:
            The resource if found, None otherwise.
        """
        return await call_next(uri, version=version)

    # -------------------------------------------------------------------------
    # Resource Templates
    # -------------------------------------------------------------------------

    async def list_resource_templates(
        self, templates: Sequence[ResourceTemplate]

   468	                meta=result.meta,
   469	            )
   470	
   471	    def get_span_attributes(self) -> dict[str, Any]:
   472	        return super().get_span_attributes() | {
   473	            "fastmcp.provider.type": "ProxyProvider",
   474	            "fastmcp.proxy.backend_name": self._backend_name,
   475	        }
   476

…[6441 chars omitted]…
],
   864	) -> mcp.types.CreateMessageResult:
   865	    """Forward sampling request from remote server to proxy's connected clients."""
1055:    async def call_tool(
1056-        self,
1057-        name: str,
1058-        arguments: dict[str, Any] | None = None,
1059-        *,
1060-        version: VersionSpec | None = None,
--
1066:    async def call_tool(
1067-        self,
1068-        name: str,

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 fastmcp.utilities.tests import temporary_settings

# Use SelectorEventLoop on Windows to avoid ProactorEventLoop crashes
# See: https://github.com/python/cpython/issues/116773
if sys.platform == "win32":
    asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())


def pytest_collection_modifyitems(items):
    """Automatically mark tests in integration_tests folder with 'integration' marker."""
    for item in items:
        
…[2552 chars omitted]…
0))
tests/server/mount/test_mount.py:248:        caplog.set_level(logging.DEBUG, logger="fastmcp")
tests/server/middleware/test_logging.py:36:        if (module or "logging") in record.name
tests/server/mount/test_mount.py:248:        caplog.set_level(logging.DEBUG, logger="fastmcp")
tests/server/test_logging.py:13:        return f"TEST_FORMAT::{record.levelname}::{record.name}::{record.getMessage()}"

253-    Attributes:
254-        parent_tool: The original tool that this tool was transformed from.
255-        fn: The function to execute when this tool is called (either
…[8630 chars omitted]…
 parent_tool=tool,
618:        parent_tool: Tool,
628:            parent_tool: The original tool to transform.
639:        parent_defs = deepcopy(parent_tool.parameters.get("$defs", {}))
640:        parent_props = deepcopy(parent_tool.parameters.get("properties", {}))
641:        parent_required = set(parent_tool.parameters.get("required", []))
734:            return await parent_tool.run(parent_args)

   512	            # User wants pure transformation - use forwarding_fn as the main function
   513	            final_fn = forwarding_fn
   514	            final_schema = schema
   515	        else:
   516	            # parsed fn i
…[8630 chars omitted]…
er: Callable[[Any], str] | NotSetT | None = NotSet,  # Deprecated
   384	        meta: dict[str, Any] | NotSetT | None = NotSet,
   385	    ) -> TransformedTool:
   386	        """Create a transformed tool from a parent tool.
   387	
   388	        Args:
   389	            tool: The parent tool to transform.
   390	            transform_fn: Optional custom function. Can use forward() and forward_raw()

  1042	                ctx = AuthContext(token=token, component=p)
  1043	                try:
  1044	                    if not await run_auth_checks(p.auth, ctx):
  1045	                        continue
  1046	                except AuthorizationError:
  1047	                    continue
  1048	            authorized.append(p)
  1049	
  1050	        if not authorized:
  1
…[8630 chars omitted]…
ror rendering prompt {name!r}")
  1434	                    if self._mask_error_details:
  1435	                        raise PromptError(f"Error rendering prompt {name!r}") from e
  1436	                    raise PromptError(f"Error rendering prompt {name!r}: {e}") from e
  1437	
  1438	    def add_tool(self, tool: Tool | Callable[..., Any]) -> Tool:
  1439	        """Add a tool to the server.
  1440

import mcp.types
from mcp.types import GetTaskResult, TaskStatusNotification

from fastmcp.client.messages import Message, MessageHandler
from fastmcp.utilities.logging import get_logger

logger = get_logger(__name__)

if TYPE_CHECKING:
    from fastmcp.client.client import CallToolResult, Client


class TaskNotificationHandler(MessageHandler):
    """MessageHandler that routes task status notifications to Task objects."""

    def __init__(self, client: Client):
        super().__init__()
        self._client_ref: weakref.ref[Client] = weakref.ref(client)

    async def dispatch(self, message: Message) -> No
…[8630 chars omitted]…

357-            task_obj = ResourceTask(
358-                self, server_task_id, uri=str(uri), immediate_result=None
359-            )
360-            self._task_registry[server_task_id] = weakref.ref(task_obj)
361-            return task_obj
362-        else:
363-            # Graceful degradation - server returned ReadResourceResult
364-            synthetic_task_id = task_id or str(uuid.uuid4())

  2202	            mcp_names=mcp_names,
  2203	            tags=tags,
  2204	        )
  2205	        return cls(name=server_name, providers=[provider], **settings)
  2206	
  2207	    @classmethod
  2208	    def as_proxy(
  2209	        cls,
  2210	        backend: (
  2211	            Client[ClientTransportT]
  2212	            | ClientTransport
  2213	            | FastMCP[Any]
  2214	            | FastMCP1Server
  2215	            | 
…[3541 chars omitted]…
                if not isinstance(server, FastMCPProxy):
2222:    ) -> FastMCPProxy:
2272:) -> FastMCPProxy:
2276:    use `FastMCPProxy` or `ProxyProvider` directly from `fastmcp.server.providers.proxy`.
2286:        **settings: Additional settings passed to FastMCPProxy (name, etc.)
2289:        A FastMCPProxy server that proxies to the target.
2303:        FastMCPProxy,
2308:    return FastMCPProxy(

    13	
    14	
    15	class TestClientToolTracing:
    16	    """Tests for client tool call tracing."""
    17	
    18	    async def test_call_tool_creates_span(self, trace_exporter: InMemorySpanExporter):
    19	        server = FastMCP("test-server")
    20	
    21	        @server.tool()
    22	        def greet(name: str) -> str:
    23	            return f"Hello, {name}!"
    24	
    25	        client = Client(server)
    26	        async with 
…[8630 chars omitted]…
len(spans) == 1
tests/server/telemetry/test_server_tracing.py:257:        assert len(spans) == 1
tests/server/telemetry/test_server_tracing.py:285:        assert len(spans) == 1
tests/server/telemetry/test_server_tracing.py:305:        assert len(spans) == 1
tests/server/telemetry/test_server_tracing.py:334:        assert len(spans) == 1
tests/telemetry/test_module.py:27:        assert len(spans) == 1

   212	        cls,
   213	        client_factory: ClientFactoryT,
   214	        mcp_resource: mcp.types.Resource,
   215	    ) -> ProxyResource:
   216	        """Factory method to create a ProxyResource from a raw MCP resource schema."""
   217	
   218	        return cls(
   219	            client_factory=clien
…[8629 chars omitted]…
   471	    def get_span_attributes(self) -> dict[str, Any]:
   472	        return super().get_span_attributes() | {
   473	            "fastmcp.provider.type": "ProxyProvider",
   474	            "fastmcp.proxy.backend_name": self._backend_name,
   475	        }
35:from fastmcp.client.telemetry import client_span
121:        with client_span(
237:        with client_span(
452:        with client_span(

   180	
   181	        Args:
   182	            component: The component to add.
   183	
   184	        Returns:
   185	            The component that was added (or existing if on_duplicate="ignore").
   186	        """
   187	        existing = self.
…[2205 chars omitted]…
te.py:216:        return self._collect_list_results(results, "list_resource_templates")
src/fastmcp/server/providers/aggregate.py:240:        return self._collect_list_results(results, "list_prompts")
src/fastmcp/server/providers/aggregate.py:262:        return self._collect_list_results(results, "get_tasks")
grep: src/fastmcp/server/providers/__pycache__/aggregate.cpython-312.pyc: binary file matches

from fastmcp.utilities.versions import VersionSpec, version_sort_key

if TYPE_CHECKING:
    from fastmcp.prompts.base import Prompt
    from fastmcp.resources.base import Resource
    from fastmcp.resources.template import ResourceTemplate
    from fastmcp.tools.base import Tool

logger = logging.getLogger(__name__)

DuplicateBehavior = Literal["warn", "error", "replace", "ignore"]

T = TypeVar("T", bound=FastMCPComponent)


cl
…[5415 chars omitted]…
n the first match.
        """
        valid: list[FastMCPComponent] = []
        for i, result in enumerate(results):
            if isinstance(result, BaseException):
                if not isinstance(result, NotFoundError):
                    logger.warning(
                        "Error during %s from provider %r: %s",
                        operation,
                        self.providers[i],

import re
from collections.abc import AsyncIterator, Sequence
from contextlib import asynccontextmanager
from typing import TYPE_CHECKING, Any, overload
from urllib.parse import quote

import mcp.types
from mcp.types import AnyUrl

from fastmcp.prompts.base import Prompt, PromptResult
from fastmcp.resources.base import Resource, ResourceResult
from fastmcp.resources.template import ResourceTemplate
from fastmcp.server.providers.base import Provider
from fastmcp.server.tasks.config imp
…[8629 chars omitted]…
if task_key:
   479	            kwargs["key"] = task_key
   480	        return await docket.add(lookup_key, **kwargs)(**params)
   481	
   482	    def get_span_attributes(self) -> dict[str, Any]:
   483	        return super().get_span_attributes() | {
   484	            "fastmcp.provider.type": "FastMCPProvider",
   485	            "fastmcp.delegate.original_uri_template": self._original_uri_template,

111:        # Find client-side resource span (doesn't have fastmcp.server.name)
112:        client_span = next(
122:        assert client_span is not None
123:        assert client_span.attributes is not N
…[6692 chars omitted]…
ixins/resources.py:16:from fastmcp.client.telemetry import client_span
src/fastmcp/client/mixins/resources.py:195:        with client_span(
src/fastmcp/client/mixins/tools.py:18:from fastmcp.client.telemetry import client_span
src/fastmcp/client/mixins/tools.py:142:        with client_span(
src/fastmcp/client/telemetry.py:12:def client_span(
src/fastmcp/client/telemetry.py:47:__all__ = ["client_span"]

            "Server span's parent should be the client span"
        )


class TestClientErrorTracing:
    """Tests for client span creation during errors.

    Note: MCP protocol errors are returned as successful responses with error content,
    so cli
…[6876 chars omitted]…
3-    context: RequestContext[ClientSession, LifespanContextT],
854-) -> RootsList:
--
983:    def __init__(
984-        self,
985-        transport: ClientTransportT
986-        | FastMCP[Any]
987-        | FastMCP1Server
988-        | AnyUrl
989-        | Path
990-        | MCPConfig
991-        | dict[str, Any]
992-        | str,
993-        **kwargs,
994-    ):
995-        if "name" not in kwargs:

   332	            return "First app tool"
   333	
   334	        @second_app.tool(name="shared_tool")
   335	        def second_shared_tool() -> str:
   336	            return "Second app tool"
   337	
   338	        # Mount both apps without prefix
   339	        main_app.mount(first_app)
   340	        main_app.mount(second_app)
   341	
   342	        # list
…[8629 chars omitted]…
ync def test_first_server_wins_prompts_no_prefix(self):
tests/server/mount/test_mount.py:487:        """Test that first mounted server wins for prompts when no prefix is used."""
tests/server/mount/test_mount.py:515:    async def test_first_server_wins_prompts_same_prefix(self):
tests/server/mount/test_mount.py:516:        """Test that first mounted server wins for prompts when same prefix is used."""

    for exc in group.exceptions:
        if isinstance(exc, BaseExceptionGroup):
            yield from iter_exc(exc)
        else:
            yield exc


def _exception_handler(group: BaseExceptionGroup):
    for leaf in iter_exc(group):
        if isinstance(leaf, httpx.ConnectTimeout):
            raise McpError(
                error=mcp.types.ErrorData(
                    code=httpx.codes.REQUEST_TIMEOUT,
                    message="Timed out while waiting for response.",
                )
            )
        raise leaf


# this catch handler is used to catch taskgroup exception groups and raise the
# first exception. This allows more sane
…[3778 chars omitted]…
 library logging,
    for compatibility with structured logging.
    """

    msg: str
    extra: Mapping[str, Any] | None = None


_mcp_level_to_python_level = {
    "debug": logging.DEBUG,
    "info": logging.INFO,
    "notice": logging.INFO,
    "warning": logging.WARNING,
    "error": logging.ERROR,
    "critical": logging.CRITICAL,
    "alert": logging.CRITICAL,
    "emergency": logging.CRITICAL,

   682	        # Separate by type for this provider's transform application
   683	        tools = [c for c in components if isinstance(c, Tool)]
   684	        resources = [c for c in components if isinstance(c, Resource)]
   685	        templates = [c for c in components if isi
…[8630 chars omitted]…
f)
   366	        logger.debug(f"[{server.name}] Handler called: set_logging_level %s", level)
   367	        try:
   368	            ctx = server._mcp_server.request_context
   369	            session = ctx.session
   370	            if isinstance(session, MiddlewareServerSession):
   371	                session._minimum_logging_level = level
   372	        except LookupError:
   373	            pass

   294	        # Resolve server default for background task support
   295	        self._support_tasks_by_default: bool = tasks if tasks is not None else False
   296	
   297	        # Docket and Worker instances (set during lifespan for cross-task access)
   298	     
…[8628 chars omitted]…
during %s from provider %r: %s",
   166	                    operation,
   167	                    self.providers[i],
   168	                    result,
   169	                )
   170	                continue
   171	            collected.extend(result)
   172	        return self._resolve_duplicate_components(collected, operation)
   173	
   174	    def _get_highest_version_result(
   175	        self,

    name: str,
    method: str,
    component_key: str,
    session_id: str | None = None,
    resource_uri: str | None = None,
) -> Generator[Span, None, None]:
    """Create a CLIENT span with standard MCP attributes.

    Automatically records any exception on the span and sets error status.
    """
    tracer = get_tracer()
    with tracer.start_as_current_span(name, kind=SpanKind.CLIENT) as span:
        attrs: dict[str, str] = {
            "mcp.method.name": method,
            "fastmcp.component.key": component_key,
        }
        if method == "tools/call":
            attrs["gen_ai.tool.name"] = component_key
        el
…[3436 chars omitted]…
eption and set its type and message on a span."""
    span.record_exception(exception)
    set_span_error(
        span,
        str(exception),
        error_type or type(exception).__name__,
    )


def extract_trace_context(meta: dict[str, Any] | None) -> Context:
    """Extract trace context from an MCP request meta dict.

    If already in a valid trace (e.g., from HTTP propagation), the existing

49-    However, this isn't feasible for user-generated functions. Instead, we use a
50-    cache to minimize the cost of creating them as much as possible.
51-    """
52-    # For functions, process annotations to handle forward references and convert
53-    # Annotated[Type, "string"] to Annotated[Type, Field(description="string")]
54-    if inspect.isfunction(cls) or inspect.ismethod(cls):
55-        if hasatt
…[2913 chars omitted]…
cp.delegate.original_uri_template": self._original_uri_template,
   486	        }
   487	
   488	
   489	# -----------------------------------------------------------------------------
   490	# FastMCPProvider
   491	# -----------------------------------------------------------------------------
   492	
   493	
   494	class FastMCPProvider(Provider):
   495	    """Provider that wraps a FastMCP server.

from fastmcp.exceptions import NotFoundError

from .middleware import CallNext, Middleware, MiddlewareContext


class ErrorHandlingMiddleware(Middleware):
    """Middleware that provides consistent error handling and logging.

    Catches exceptions, logs them appropriately, and converts them to
    proper MCP error responses. Also tracks error patterns for monitoring.

    Example:
        ```python
        from fastmcp.server.middleware.error_handling import ErrorHandlingMiddleware
        import logging

        # Configure logging to see error details
        logging.basicConfig(level=logging.ERROR)

        mcp = FastMCP("MySer
…[5359 chars omitted]…
                       if self._mask_error_details:
src/fastmcp/server/server.py:1337:                    if self._mask_error_details:
src/fastmcp/server/server.py:1435:                    if self._mask_error_details:
src/fastmcp/server/server.py:1990:        if self._mask_error_details and not server._mask_error_details:
grep: src/fastmcp/server/__pycache__/server.cpython-312.pyc: binary file matches

    82	    _original_name: str | None = None
    83	    _mask_error_details: bool = False
    84	    _mask_error_details: bool = False
    85	
    86	    def __init__(
    87	        self,
    88	        server: Any,
    89	        original_name: str,
    90	        mask_error_details: bool = False,
    91	        **kwargs: Any,
    92	    ):
    93	        super().__init__(**kwargs)

…[8629 chars omitted]…
late]:
   719	        """List all resource templates from the mounted server.
   720	
   721	        Runs the mounted server's middleware so filtering/transformation applies.
   722	        Returns FastMCPProviderResourceTemplate instances that create
   723	        FastMCPProviderResources when materialized.
   724	        """
   725	        raw_templates = await self.server.list_resource_templates()

424:        self._mask_error_details = mask_error_details
465:            mask_error_details=self._mask_error_details,
505:            if self._mask_error_details:
527:            if self._mask_error_details:
618:        self._mask_error_details = mask_error_details
620:    def with_mask_error_details(self, mask_error_details: bool
…[8630 chars omitted]…
k_error_details
   782	        )
   783	
   784	    # -------------------------------------------------------------------------
   785	    # Task registration
   786	    # -------------------------------------------------------------------------
   787	
   788	    async def get_tasks(self) -> Sequence[FastMCPComponent]:
   789	        """Return task-eligible components from the mounted server.
   790

   207	    _original_uri: str | None = None
   208	    _mask_error_details: bool = False
   209	
   210	    def __init__(
   211	        self,
   212	        server: Any,
   213	        original_uri: str,
   214	        mask_error_details: bool = False,
   215	        **kwargs: Any,
   216	    ):
   217	        super().__init__(**kwargs)
   218	        self._server = server
   21
…[8629 chars omitted]…

   388	        # Result from render_prompt should always be PromptResult when no task_meta
   389	        if isinstance(result, mcp.types.CreateTaskResult):
   390	            raise RuntimeError(
   391	                "Unexpected CreateTaskResult from render_prompt without task_meta"
   392	            )
   393	        return result
   394	
   395	    def get_span_attributes(self) -> dict[str, Any]:

   302	        super().__init__(**kwargs)
   303	        self._server = server
   304	        self._original_name = original_name
   305	        self._mask_error_details = mask_error_details
   306	
   307	    @classmethod
   308	    def wrap(
   309	        cls,
   310	        server: Any,
   311	        prompt: Prompt,
   312	        *,
   313	        mask_error_details: bool = False,
   314	    ) -> FastMCPProviderPrompt:
   315	        """Wrap a Prompt to delegate rendering to the server's middleware."""
   316	        return cls(
  
…[3867 chars omitted]…
error_details or mask_error_details
   114	            )
   115	
   116	        # Apply namespace via wrap_transform if specified
   117	        if namespace:
   118	            provider = provider.wrap_transform(Namespace(namespace))
   119	
   120	        self.providers.append(provider)
   121	
   122	    def _resolve_duplicate_components(
   123	        self, components: Sequence[T], operation: str

 from fastmcp.utilities.timeout import normalize_timeout_to_timedelta
@@ -144,7 +144,7 @@ class ClientToolsMixin:
             "tools/call",
             name,
             session_id=self.transport.get_session_id(),
-        ):
+        ) as span:
        
…[8629 chars omitted]…
sk_obj
   362	        else:
   363	            # Graceful degradation - server returned ReadResourceResult
   364	            synthetic_task_id = task_id or str(uuid.uuid4())
   365	            return ResourceTask(
   366	                self,
   367	                synthetic_task_id,
   368	                uri=str(uri),
   369	                immediate_result=raw_result.contents,
   370	            )

 
-from fastmcp.telemetry import get_tracer
+from fastmcp.telemetry import get_tracer, record_span_error
+
+_active_client_operation: ContextVar[tuple[Span, str, str, str] | None] = ContextVar(
+    "fastmcp_active_client_operation", default=None
+)
 
 
 @contextmanager
@@ -20,28 +25,49 @@ def client_span(
 
     Automatically records any exception on the span and sets error status.
     """
+    active_operation = _active_client_operation.get()
+    if ac
…[4699 chars omitted]…
       if method == "tools/call" and type(e).__name__ == "ToolError"
    65	                    else None
    66	                )
    67	                record_span_error(span, e, error_type=error_type)
    68	                raise
    69	        finally:
    70	            _active_client_operation.reset(token)
    71	
    72	
    73	__all__ = ["client_span"]
308:    async def _read_resource_as_task(

   287	            "prompts/get",
   288	            name,
   289	            session_id=self.transport.get_session_id(),
   290	        ):
   291	            request = mcp.types.GetPromptRequest(
   292	                params=mcp.types.GetPromptRequestParams(
   293	                    name=name,
   294	                    arguments=serialized_arguments,
   295	                   
…[4156 chars omitted]…
 359	        if isinstance(raw_result, mcp.types.CreateTaskResult):
   360	            # Task was accepted - extract task info from CreateTaskResult
   361	            server_task_id = raw_result.task.taskId
   362	            self._submitted_task_ids.add(server_task_id)
   363	
   364	            task_obj = ResourceTask(
   365	                self, server_task_id, uri=str(uri), immediate_result=None

   270	        Raises:
   271	            ToolError: If the tool call results in an error.
   272
…[6001 chars omitted]…
ce for background execution (SEP-1686).
   324	
   325	        Returns a ResourceTask object that handles both background and immediate execution.
   326	
   327	        Args:
   328	            uri: Resource URI to read
   329	            task_id: Optional client-provided task ID (ignored, for backward compatibility)
   330	            ttl: Time to keep results available in milliseconds (default 60s)

   167	            "fastmcp.proxy.backend_name": self._backend_name,
   168	        }
   169	
   170	
   171	class ProxyResource(Resource):
   172	    """A Resource that represents and reads a resource from a remote server."""
   173	
   174	    task_config: TaskConfig = TaskConfig(mode="forbidden")
   175	    _cached_content: ResourceResult | None = None

   122	            f"tools/call {backend_name}", "tools/call", backend_name
   123	        ) as span:
   124	            span.set_attribute("fastmcp.provider.type", "ProxyProvider")
   125	            client = await self._get_client()
   126	            async with client:
   127	                ctx = context or get_context()
   128	                # StatefulProxyClient reuses sessions across requests, so
   
…[2941 chars omitted]…
t_attribute("fastmcp.provider.type", "ProxyProvider")
   244	            client = await self._get_client()
   245	            async with client:
   246	                result = await client.read_resource(backend_uri)
   247	            if not result:
   248	                raise ResourceError(
   249	                    f"Remote server returned empty content for {backend_uri}"
   250	                )