π The fast, Pythonic way to build MCP servers and clients.
from typing import Any
from unittest.mock import AsyncMock, patch
import mcp_types
import pytest
from jsonschema import validate
from mcp.server.context import ServerRequestContext
from mcp.server.lowlevel.server import Server
from mcp.server.transport_security import TransportSecuritySettings
from fastmcp import Client, FastMCP
from fastmcp.server.middleware import Middleware
from fastmcp.server.middleware.caching import ResponseCachingMiddleware
from fastmcp.server.providers.proxy import ProxyClient, ProxyProvider, ProxyTool
from fastmcp.server.transforms.tool_transform import ToolTransform
from fastmcp.tools.base import RawStructuredToolResult, Tool, ToolResult
from fastmcp.tools.tool_transform import ToolTransformConfig
from fastmcp.utilities.asgi_transport import run_asgi_lifespan
from fastmcp.utilities.tests import ASGIServer
@pytest.mark.parametrize("mode", ["legacy", "auto"])
@pytest.mark.parametrize("cache_results", [False, True])
@pytest.mark.parametrize("transform_results", [False, True])
async def test_proxy_preserves_non_object_tool_outputs_across_protocol_versions(
mode: str,
cache_results: bool,
transform_results: bool,
) -> None:
schemas = {
"numbers": {"type": "array", "items": {"type": "integer"}},
"flag": {"type": "boolean"},
"record": {"type": "object", "properties": {"value": {"type": "integer"}}},
"matrix": {
"type": "array",
"items": {"$ref": "#/$defs/row"},
"$defs": {"row": {"type": "array", "items": {"type": "integer"}}},
},
"old_matrix": {
"type": "array",
"items": {"$ref": "#/definitions/row"},
"definitions": {"row": {"type": "array", "items": {"type": "integer"}}},
},
"missing": None,
"unconstrained": {},
"choice": {
"oneOf": [
{"type": "object", "properties": {"value": {"type": "integer"}}},
{"type": "array", "items": {"type": "integer"}},
]
},
}
values = {
"numbers": [1, 2, 3],
"flag": False,
"record": {"value": 1},
"matrix": [[1, 2]],
"old_matrix": [[3, 4]],
"choice": {"value": 2},
"unconstrained": {"value": 3},
}
calls = {name: 0 for name in schemas}
async def list_tools(
ctx: ServerRequestContext[Any, Any],
params: mcp_types.PaginatedRequestParams | None,
) -> mcp_types.ListToolsResult:
return mcp_types.ListToolsResult(
tools=[
mcp_types.Tool(
name=name,
input_schema={"type": "object", "properties": {}},
output_schema=schema,
)
for name, schema in schemas.items()
]
)
async def call_tool(
ctx: ServerRequestContext[Any, Any],
params: mcp_types.CallToolRequestParams,
) -> mcp_types.CallToolResult:
calls[params.name] += 1
if params.name == "missing":
return mcp_types.CallToolResult(content=[])
value = values[params.name]
return mcp_types.CallToolResult(
content=[mcp_types.TextContent(type="text", text=str(value))],
structured_content=value,
_meta={"source": "backend"},
)
backend = Server("backend", on_list_tools=list_tools, on_call_tool=call_tool)
app = backend.streamable_http_app(
stateless_http=True,
transport_security=TransportSecuritySettings(allowed_hosts=["127.0.0.1"]),
)
async with run_asgi_lifespan(app):
upstream = ASGIServer("http://127.0.0.1/mcp", app, "http")
proxy = FastMCP("proxy")
proxy.add_provider(
ProxyProvider(lambda: ProxyClient(upstream.transport(), mode="auto"))
)
tool_name = "renamed_numbers" if transform_results else "numbers"
if transform_results:
proxy.add_transform(
ToolTransform({"numbers": ToolTransformConfig(name="renamed_numbers")})
)
@proxy.tool(output_schema={"properties": {"value": {"type": "integer"}}})
def plain_record() -> dict[str, int]:
return {"value": 7}
@proxy.tool
async def nested_numbers() -> dict[str, Any]:
result = await proxy.call_tool(tool_name, {})
return {"value": result.structured_content}
if cache_results:
proxy.add_middleware(ResponseCachingMiddleware())
async with Client(proxy, mode=mode) as client:
tools = {tool.name: tool for tool in await client.list_tools()}
numbers = await client.call_tool(tool_name, {})
flag = await client.call_tool("flag", {})
record = await client.call_tool("record", {})
matrix = await client.call_tool("matrix", {})
old_matrix = await client.call_tool("old_matrix", {})
missing = await client.call_tool_mcp("missing", {})
choice = await client.call_tool("choice", {})
unconstrained = await client.call_tool("unconstrained", {})
plain = await client.call_tool("plain_record", {})
nested = await client.call_tool("nested_numbers", {})
if cache_results:
numbers_cached = await client.call_tool(tool_name, {})
assert numbers_cached.structured_content == numbers.structured_content
assert calls["numbers"] == 1
if cache_results:
other_mode = "auto" if mode == "legacy" else "legacy"
async with Client(proxy, mode=other_mode) as other_client:
other_numbers = await other_client.call_tool(tool_name, {})
assert other_numbers.structured_content == (
[1, 2, 3] if mode == "legacy" else {"result": [1, 2, 3]}
)
assert calls["numbers"] == 2
assert numbers.data == [1, 2, 3]
assert flag.data is False
assert record.data.value == 1
assert numbers.meta["source"] == "backend"
assert flag.meta["source"] == "backend"
assert record.structured_content == {"value": 1}
assert matrix.data == [[1, 2]]
assert old_matrix.data == [[3, 4]]
assert choice.data == {"value": 2}
assert unconstrained.data == {"value": 3}
assert missing.structured_content is None
assert plain.structured_content == {"value": 7}
assert nested.structured_content == {"value": [1, 2, 3]}
assert tools["plain_record"].output_schema == {
**({"type": "object"} if mode == "legacy" else {}),
"properties": {"value": {"type": "integer"}},
}
assert tools["record"].output_schema == schemas["record"]
if mode == "auto":
assert tools[tool_name].output_schema == schemas["numbers"]
assert tools["unconstrained"].output_schema == {}
assert numbers.structured_content == [1, 2, 3]
assert flag.structured_content is False
assert choice.structured_content == {"value": 2}
else:
assert tools[tool_name].output_schema["type"] == "object"
assert (
tools[tool_name].output_schema["properties"]["result"] == schemas["numbers"]
)
assert tools["unconstrained"].output_schema["type"] == "object"
assert tools["unconstrained"].output_schema["properties"]["result"] == {}
assert numbers.structured_content == {"result": [1, 2, 3]}
assert unconstrained.structured_content == {"result": {"value": 3}}
assert flag.structured_content == {"result": False}
assert choice.structured_content == {"result": {"value": 2}}
validate(matrix.structured_content, tools["matrix"].output_schema)
validate(old_matrix.structured_content, tools["old_matrix"].output_schema)
@pytest.mark.parametrize("mode", ["legacy", "auto"])
async def test_proxy_middleware_edits_reach_clients_and_cache(mode: str) -> None:
observed: list[Any] = []
backend_calls = 0
async def list_tools(
ctx: ServerRequestContext[Any, Any],
params: mcp_types.PaginatedRequestParams | None,
) -> mcp_types.ListToolsResult:
return mcp_types.ListToolsResult(
tools=[
mcp_types.Tool(
name="numbers",
input_schema={"type": "object"},
output_schema={"type": "array", "items": {"type": "integer"}},
)
]
)
async def call_tool(
ctx: ServerRequestContext[Any, Any],
params: mcp_types.CallToolRequestParams,
) -> mcp_types.CallToolResult:
nonlocal backend_calls
backend_calls += 1
return mcp_types.CallToolResult(
content=[mcp_types.TextContent(type="text", text="original")],
structured_content=[1, 2, 3],
_meta={"source": "backend"},
)
class RedactMiddleware(Middleware):
async def on_call_tool(self, context, call_next):
result = await call_next(context)
observed.append(result.structured_content)
return result.model_copy(update={"structured_content": [9]})
backend = Server("backend", on_list_tools=list_tools, on_call_tool=call_tool)
app = backend.streamable_http_app(
stateless_http=True,
transport_security=TransportSecuritySettings(allowed_hosts=["127.0.0.1"]),
)
async with run_asgi_lifespan(app):
upstream = ASGIServer("http://127.0.0.1/mcp", app, "http")
proxy = FastMCP("proxy")
proxy.add_provider(
ProxyProvider(lambda: ProxyClient(upstream.transport(), mode="auto"))
)
proxy.add_middleware(ResponseCachingMiddleware())
proxy.add_middleware(RedactMiddleware())
async with Client(proxy, mode=mode) as client:
first = await client.call_tool("numbers", {})
cached = await client.call_tool("numbers", {})
assert observed == [[1, 2, 3]]
expected = {"result": [9]} if mode == "legacy" else [9]
assert first.structured_content == expected
assert cached.structured_content == expected
assert first.meta["source"] == "backend"
assert backend_calls == 1
async def test_legacy_proxy_wraps_explicit_null_from_backend_model() -> None:
# The SDK currently omits null fields during wire serialization, so
# inject the backend model directly to exercise presence detection.
explicit_null = mcp_types.CallToolResult(content=[], structured_content=None)
absent = mcp_types.CallToolResult(content=[])
assert "structured_content" in explicit_null.model_fields_set
assert "structured_content" not in absent.model_fields_set
backend = FastMCP("backend")
proxy = FastMCP("proxy")
proxy.add_tool(
ProxyTool(
client_factory=lambda: ProxyClient(backend, mode="legacy"),
name="nullable",
parameters={"type": "object"},
output_schema={"type": "null"},
)
)
with patch.object(
ProxyClient,
"call_tool_mcp",
new_callable=AsyncMock,
return_value=explicit_null,
):
async with Client(proxy, mode="legacy") as client:
result = await client.call_tool_mcp("nullable", {})
assert result.structured_content == {"result": None}
@pytest.mark.parametrize("mode", ["legacy", "auto"])
@pytest.mark.parametrize("transform_results", [False, True])
@pytest.mark.parametrize("raw_output", [False, True])
@pytest.mark.parametrize(
"schema",
[
{},
{
"oneOf": [
{"type": "object", "properties": {"value": {"type": "integer"}}},
{"type": "array", "items": {"type": "integer"}},
]
},
{
"type": ["object", "array"],
"properties": {"value": {"type": "integer"}},
},
],
)
async def test_custom_tool_result_matches_legacy_advertised_wrapper(
mode: str,
transform_results: bool,
raw_output: bool,
schema: dict[str, Any],
) -> None:
class CustomTool(Tool):
async def run(self, arguments: dict[str, Any]) -> ToolResult:
if raw_output:
return RawStructuredToolResult(content=[], structured_content=[1])
return self.convert_result({"value": 1})
server = FastMCP("custom")
server.add_tool(
CustomTool(
name="custom",
parameters={"type": "object", "properties": {}},
output_schema=schema,
)
)
tool_name = "renamed_custom" if transform_results else "custom"
if transform_results:
server.add_transform(
ToolTransform({"custom": ToolTransformConfig(name=tool_name)})
)
direct = await server.call_tool(tool_name, {})
expected = [1] if raw_output else {"value": 1}
assert direct.structured_content == expected
async with Client(server, mode=mode) as client:
advertised = (await client.list_tools())[0].output_schema
result = await client.call_tool_mcp(tool_name, {})
if mode == "legacy":
assert advertised["properties"]["result"] == schema
assert result.structured_content == {"result": expected}
else:
assert advertised == schema
assert result.structured_content == expected