Skip to content

🚀 The fast, Pythonic way to build MCP servers and clients.

ci: add langchain.mcp and a FastMCP proxy to the downstream smoke (#5222)

nate nowack3ca425416ea4
diff --git a/.github/workflows/run-downstream-smoke.yml b/.github/workflows/run-downstream-smoke.yml
index 8476d9b6b..ebaf06f1b 100644
--- a/.github/workflows/run-downstream-smoke.yml
+++ b/.github/workflows/run-downstream-smoke.yml
@@ -168,6 +168,65 @@ jobs:
if: always() && hashFiles('junit.xml') != ''
run: python3 fastmcp/tests/downstream/_harness.py junit.xml "pydantic-ai ${{ needs.plan.outputs.pydantic-ai }} MCP test suite"
+ langchain-suite:
+ name: langchain test suite
+ needs: plan
+ runs-on: ubuntu-latest
+ timeout-minutes: 15
+ steps:
+ - uses: actions/checkout@v7
+ with:
+ path: fastmcp
+
+ - uses: actions/checkout@v7
+ with:
+ repository: langchain-ai/langchain
+ ref: langchain==${{ needs.plan.outputs.langchain }}
+ path: langchain
+ persist-credentials: false
+
+ - uses: actions/download-artifact@v8
+ with:
+ name: fastmcp-wheels
+ path: dist
+
+ - name: Install uv
+ uses: astral-sh/[email protected]
+ with:
+ python-version: "3.13"
+ enable-cache: true
+ cache-dependency-glob: langchain/libs/langchain_v1/uv.lock
+
+ # langchain.mcp builds on fastmcp.Client and ClientGroup; run its own MCP
+ # tests in its locked environment with FastMCP overlaid from the wheels.
+ - name: Resolve environment
+ working-directory: langchain/libs/langchain_v1
+ run: |
+ echo "UV_RUN=uv run --group test \
+ --with fastmcp@file://$(ls $GITHUB_WORKSPACE/dist/fastmcp-4*.whl) \
+ --with fastmcp-slim@file://$(ls $GITHUB_WORKSPACE/dist/fastmcp_slim-*.whl)" >> "$GITHUB_ENV"
+
+ - name: Check the build under test is installed
+ working-directory: langchain/libs/langchain_v1
+ run: >-
+ $UV_RUN --quiet python -c "import fastmcp;
+ assert fastmcp.__version__ == '${{ needs.plan.outputs.fastmcp }}', fastmcp.__version__;
+ print('fastmcp', fastmcp.__version__)"
+
+ # The deselected test asserts on the caller's Client while MCPAdapter
+ # connects a clone, so it fails against every fastmcp 4.0.x release.
+ - name: Run langchain's MCP tests
+ working-directory: langchain/libs/langchain_v1
+ run: >-
+ $UV_RUN --quiet pytest -p no:cacheprovider -q
+ --junitxml=$GITHUB_WORKSPACE/junit.xml
+ tests/unit_tests/mcp tests/integration_tests/mcp
+ --deselect tests/integration_tests/mcp/test_protocol_eras.py::test_separate_adapters_keep_their_own_protocol_era
+
+ - name: Summarize
+ if: always() && hashFiles('junit.xml') != ''
+ run: python3 fastmcp/tests/downstream/_harness.py junit.xml "langchain ${{ needs.plan.outputs.langchain }} MCP test suite"
+
smoke:
name: ${{ matrix.consumer }} smoke
needs: plan
@@ -183,9 +242,16 @@ jobs:
with: >-
--with "pydantic-ai-slim[mcp]==${{ needs.plan.outputs.pydantic-ai }}"
--with "fastmcp-slim[client] @ file://$GITHUB_WORKSPACE/$(ls dist/fastmcp_slim-*.whl)"
+ # langchain.mcp wraps fastmcp.Client and ClientGroup, with the build under test.
+ - consumer: langchain.mcp
+ script: smoke_langchain_mcp.py
+ with: >-
+ --with "langchain[mcp]==${{ needs.plan.outputs.langchain }}"
+ --with "fastmcp @ file://$GITHUB_WORKSPACE/$(ls dist/fastmcp-4*.whl)"
+ --with "fastmcp-slim @ file://$GITHUB_WORKSPACE/$(ls dist/fastmcp_slim-*.whl)"
# The adapters pin mcp<2, so they reach FastMCP over the wire.
- - consumer: langchain
- script: smoke_langchain.py
+ - consumer: langchain-mcp-adapters
+ script: smoke_langchain_mcp_adapters.py
with: >-
--with "langchain-mcp-adapters==${{ needs.plan.outputs.langchain-mcp-adapters }}"
--with "langchain==${{ needs.plan.outputs.langchain }}"
diff --git a/tests/downstream/README.md b/tests/downstream/README.md
index 4ba87bbcf..17d8c349b 100644
--- a/tests/downstream/README.md
+++ b/tests/downstream/README.md
@@ -7,13 +7,24 @@ against servers started from the checkout.
| job | what it runs | FastMCP install |
|---|---|---|
-| pydantic-ai test suite | pydantic-ai's own `tests/test_mcp.py` and sampling tests at a pinned tag | wheels overlaid on pydantic-ai's locked environment, as their FastMCP 4 job does |
-| pydantic-ai smoke | `smoke_pydantic_ai.py` over stdio, `mcp.json` config, streamable HTTP and SSE | client-only `fastmcp-slim[client]`, as `pydantic-ai-slim[mcp]` installs it |
-| langchain smoke | `smoke_langchain.py` over stdio, streamable HTTP and SSE | none: the adapters pin `mcp<2`, so they reach FastMCP over the wire |
-
-HTTP and SSE servers require a bearer token. Each smoke prints one line per
-check, writes a table to the job summary, and reports warnings raised in the
-consumer's process.
+| pydantic-ai test suite | pydantic-ai's own MCP tests at a pinned tag | wheels overlaid on pydantic-ai's locked environment, as their FastMCP 4 job does |
+| langchain test suite | `langchain.mcp`'s own unit and integration tests at a pinned tag | wheels overlaid on langchain's locked test environment |
+| pydantic-ai smoke | `smoke_pydantic_ai.py` | client-only `fastmcp-slim[client]`, as `pydantic-ai-slim[mcp]` installs it |
+| langchain.mcp smoke | `smoke_langchain_mcp.py`, including a `ClientGroup` of a legacy HTTP server and a modern stdio server | `fastmcp`, as `langchain[mcp]` installs it |
+| langchain-mcp-adapters smoke | `smoke_langchain_mcp_adapters.py` | none: the adapters pin `mcp<2`, so they reach FastMCP over the wire |
+
+Each smoke runs its checks over stdio, streamable HTTP, SSE, and a FastMCP proxy
+in front of a stdio server, all with bearer auth where the transport allows it.
+The checks cover shapes past releases got wrong: template literals such as `|`
+and non-ASCII, comma-joined and exploded list query params, elicitation in both
+protocol eras, schema counts written as floats, and a timed-out call followed by
+another on the same connection.
+
+Each smoke prints one line per check, writes a table to the job summary, and
+reports warnings raised in the consumer's process. A check listed in
+`_harness.py`'s `PROXY_GAPS` or `LEGACY_PROXY_GAPS` is a gap the proxy already
+had in 4.0.5: it shows as ⚠ without failing the run, and fails the run if it
+starts passing so the entry gets removed.
Pushes and PRs test the versions pinned in the workflow. The nightly run, or a
manual run with `latest`, tests each consumer's latest release.
@@ -22,14 +33,19 @@ manual run with `latest`, tests each consumer's latest release.
```bash
uv sync
-uv build --wheel --out-dir dist fastmcp_slim
+uv build --wheel --out-dir dist . fastmcp_slim
+slim="fastmcp-slim @ file://$PWD/$(ls dist/fastmcp_slim-*.whl)"
+full="fastmcp @ file://$PWD/$(ls dist/fastmcp-4*.whl)"
uv run --isolated --no-project --no-config \
- --with 'pydantic-ai-slim[mcp]' \
- --with "fastmcp-slim[client] @ file://$PWD/$(ls dist/fastmcp_slim-*.whl)" \
+ --with 'pydantic-ai-slim[mcp]' --with "${slim/fastmcp-slim/fastmcp-slim[client]}" \
python tests/downstream/smoke_pydantic_ai.py
+uv run --isolated --no-project --no-config \
+ --with 'langchain[mcp]' --with "$full" --with "$slim" \
+ python tests/downstream/smoke_langchain_mcp.py
+
uv run --isolated --no-project --no-config \
--with langchain-mcp-adapters --with langchain \
- python tests/downstream/smoke_langchain.py
+ python tests/downstream/smoke_langchain_mcp_adapters.py
```
diff --git a/tests/downstream/_harness.py b/tests/downstream/_harness.py
index 19f58e902..15e63c0a3 100644
--- a/tests/downstream/_harness.py
+++ b/tests/downstream/_harness.py
@@ -1,10 +1,12 @@
"""Shared plumbing for the downstream smoke scripts: server processes and reporting."""
+import logging
import os
import secrets
import socket
import subprocess
import sys
+import tempfile
import time
import traceback
import warnings
@@ -12,13 +14,51 @@ from collections.abc import Awaitable, Callable, Iterator
from contextlib import contextmanager
from dataclasses import dataclass, field
from pathlib import Path
+from typing import Any
HERE = Path(__file__).parent
SERVER = HERE / "server.py"
REPO = HERE.parents[1]
INSTRUCTIONS = "Arithmetic and weather for smoke tests."
IN_ACTIONS = os.environ.get("GITHUB_ACTIONS") == "true"
+# Server stderr (for example a broken pipe after a check cancels a call on purpose)
+# goes here instead of into the consumer's output; `finish` points at it on failure.
+SERVER_LOG = Path(tempfile.gettempdir()) / f"downstream-smoke-{os.getpid()}.log"
+TOOLS = {
+ "add",
+ "forecast",
+ "divide",
+ "count_to",
+ "snapshot",
+ "chime",
+ "attachments",
+ "confirm",
+ "sleep",
+ "stamp",
+}
+# Gaps a FastMCP proxy already had in 4.0.5. Checks named here are expected to
+# fail through the proxy and are reported as known gaps, not failures.
+PROXY_GAPS = {
+ "logging": "a proxy with a stdio backend drops log messages (also in 4.0.5)",
+}
+LEGACY_PROXY_GAPS = {
+ **PROXY_GAPS,
+ "elicitation": (
+ "a handshake-era client gets no elicitation through a proxy whose backend "
+ "negotiated 2026-07-28 (also in 4.0.5)"
+ ),
+}
+# Template reads that past releases got wrong: literals `AnyUrl` leaves as written
+# or encodes, and both list query styles, each with the text the server returns.
+TEMPLATE_READS = {
+ "data://pair/one|two": "one+two",
+ "data://docs/café/x": "doc x",
+ "items://books?tags=a%2Cb,c": '{"category": "books", "tags": ["a,b", "c"]}',
+ "ids://books?ids=1&ids=2": '{"category": "books", "ids": [1, 2]}',
+}
os.environ.setdefault("PYDANTIC_AI_NO_BANNER", "1")
+# In-process servers and FastMCP clients log into the consumer's output; checks report failures.
+os.environ.setdefault("FASTMCP_LOG_LEVEL", "CRITICAL")
def server_python() -> str:
@@ -29,14 +69,28 @@ def server_python() -> str:
def server_env() -> dict[str, str]:
- """Keep the server's own logs and warnings out of the consumer's output."""
- return {**os.environ, "FASTMCP_LOG_LEVEL": "CRITICAL", "PYTHONWARNINGS": "ignore"}
+ """Keep the server's own logs, warnings, and stderr out of the consumer's output."""
+ return {
+ **os.environ,
+ "FASTMCP_LOG_LEVEL": "CRITICAL",
+ "PYTHONWARNINGS": "ignore",
+ "DOWNSTREAM_SMOKE_SERVER_LOG": str(SERVER_LOG),
+ }
def stdio_command() -> tuple[str, list[str]]:
return server_python(), [str(SERVER), "stdio"]
+def stdio_transport() -> Any:
+ """A FastMCP StdioTransport for the smoke server; imported lazily so consumers
+ that reach FastMCP only over the wire never import it."""
+ from fastmcp.client.transports import StdioTransport
+
+ command, args = stdio_command()
+ return StdioTransport(command, args, env=server_env())
+
+
@dataclass
class Server:
url: str
@@ -49,7 +103,7 @@ class Server:
@contextmanager
def serve(transport: str) -> Iterator[Server]:
- """Run server.py over `http` or `sse` with bearer auth for the length of the block."""
+ """Run server.py over `http`, `sse`, or `proxy` (HTTP) with bearer auth for the block."""
with socket.socket() as sock:
sock.bind(("127.0.0.1", 0))
port = sock.getsockname()[1]
@@ -78,12 +132,26 @@ def serve(transport: str) -> Iterator[Server]:
proc.wait(timeout=10)
+@contextmanager
+def quiet(*loggers: str) -> Iterator[None]:
+ """Silence loggers that report an interruption a check causes on purpose."""
+ saved = {name: logging.getLogger(name).level for name in loggers}
+ for name in loggers:
+ logging.getLogger(name).setLevel(logging.CRITICAL + 1)
+ try:
+ yield
+ finally:
+ for name, level in saved.items():
+ logging.getLogger(name).setLevel(level)
+
+
@dataclass
class Result:
transport: str
check: str
error: str | None
seconds: float
+ gap: str | None = None
@dataclass
@@ -114,14 +182,34 @@ class Report:
if IN_ACTIONS:
print("::endgroup::")
- async def check(self, name: str, fn: Callable[[], Awaitable[object]]) -> None:
+ async def check(
+ self,
+ name: str,
+ fn: Callable[[], Awaitable[object]],
+ *,
+ known_gap: str | None = None,
+ ) -> None:
+ """Run one check. A `known_gap` check is expected to fail and is reported
+ without failing the run; if it starts passing, the run fails so the
+ marker gets removed."""
start = time.monotonic()
try:
await fn()
error = None
except Exception as exc:
error = exc
- self._record(name, error, time.monotonic() - start)
+ seconds = time.monotonic() - start
+ if known_gap is None:
+ self._record(name, error, seconds)
+ elif error is None:
+ self._record(
+ name,
+ AssertionError(f"known gap now passes, remove its marker: {known_gap}"),
+ seconds,
+ )
+ else:
+ self.results.append(Result(self._transport, name, None, seconds, known_gap))
+ print(f" ⚠ {name:<34} {seconds * 1000:6.0f} ms known gap: {known_gap}")
def _record(self, name: str, error: BaseException | None, seconds: float) -> None:
detail = None if error is None else f"{type(error).__name__}: {error}"
@@ -139,9 +227,10 @@ class Report:
transports = list(dict.fromkeys(r.transport for r in self.results))
checks = list(dict.fromkeys(r.check for r in self.results))
cell = {
- (r.transport, r.check): ("✅" if not r.error else "❌")
+ (r.transport, r.check): "❌" if r.error else "⚠️" if r.gap else "✅"
for r in self.results
}
+ gaps = {(r.transport, r.check): r.gap for r in self.results if r.gap}
lines = [
f"### {'❌' if failed else '✅'} {self.consumer}",
@@ -160,6 +249,9 @@ class Report:
if failed:
lines += ["", "**Failures**", ""]
lines += [f"- `{r.transport}` / `{r.check}`: {r.error}" for r in failed]
+ if gaps:
+ lines += ["", "**Known gaps**", ""]
+ lines += [f"- `{t}` / `{c}`: {gap}" for (t, c), gap in gaps.items()]
if self.warnings:
lines += [
"",
@@ -183,6 +275,8 @@ class Report:
with open(path, "a") as fh:
fh.write(summary)
if failed:
+ if SERVER_LOG.exists():
+ print(f"stdio server stderr: {SERVER_LOG}")
sys.exit(1)
diff --git a/tests/downstream/server.py b/tests/downstream/server.py
index e28ee8f3d..54312337b 100644
--- a/tests/downstream/server.py
+++ b/tests/downstream/server.py
@@ -3,12 +3,16 @@
python server.py stdio
python server.py http <port> <bearer-token>
python server.py sse <port> <bearer-token>
+python server.py proxy <port> <bearer-token> (a FastMCP proxy in front of the stdio server)
"""
import base64
+import json
+import os
import sys
from dataclasses import dataclass
+import anyio
from _harness import INSTRUCTIONS
from mcp.types import (
ElicitRequest,
@@ -21,10 +25,12 @@ from mcp.types import (
TextResourceContents,
)
from mcp_types.version import MODERN_PROTOCOL_VERSIONS
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
from fastmcp import Context, FastMCP
+from fastmcp.client.transports import StdioTransport
from fastmcp.exceptions import ToolError
+from fastmcp.server import create_proxy
from fastmcp.server.auth.providers.jwt import StaticTokenVerifier
from fastmcp.utilities.types import Audio, Image
@@ -144,6 +150,41 @@ def build(auth_token: str | None = None) -> FastMCP:
return f"{action}: approved"
return f"{action}: {result.action}"
+ @mcp.tool
+ async def sleep(seconds: float) -> str:
+ """Sleep, so a caller can time out mid-call and then reuse the connection."""
+ await anyio.sleep(seconds)
+ return "slept"
+
+ @mcp.tool(
+ output_schema={
+ "type": "object",
+ "properties": {
+ "when": {"type": "string", "format": "date-time", "maxLength": 20.0}
+ },
+ "required": ["when"],
+ }
+ )
+ def stamp() -> dict[str, str]:
+ """Structured output whose schema writes a count as a float."""
+ return {"when": "2026-09-22T00:00:00Z"}
+
+ @mcp.resource("data://pair/{a}|{b}")
+ def pair(a: str, b: str) -> str:
+ return f"{a}+{b}"
+
+ @mcp.resource("data://docs/café/{name}")
+ def doc(name: str) -> str:
+ return f"doc {name}"
+
+ @mcp.resource("items://{category}{?tags}")
+ def tagged(category: str, tags: list[str] = Field(default_factory=list)) -> str:
+ return json.dumps({"category": category, "tags": tags})
+
+ @mcp.resource("ids://{category}{?ids*}")
+ def by_id(category: str, ids: list[int] = Field(default_factory=list)) -> str:
+ return json.dumps({"category": category, "ids": ids})
+
@mcp.resource("config://app", mime_type="application/json")
def app_config() -> str:
return '{"mode": "smoke"}'
@@ -161,9 +202,26 @@ def build(auth_token: str | None = None) -> FastMCP:
if __name__ == "__main__":
+ if log := os.environ.get("DOWNSTREAM_SMOKE_SERVER_LOG"):
+ sys.stderr = open(log, "a") # noqa: SIM115
match sys.argv[1:]:
case [] | ["stdio"]:
build().run("stdio", show_banner=False)
+ case ["proxy", port, token]:
+ backend = StdioTransport(
+ sys.executable, [__file__, "stdio"], env=dict(os.environ)
+ )
+ proxy = create_proxy(backend, name="downstream-smoke")
+ proxy.auth = StaticTokenVerifier(
+ {token: {"client_id": "smoke", "scopes": []}}
+ )
+ proxy.run(
+ "http",
+ host="127.0.0.1",
+ port=int(port),
+ show_banner=False,
+ log_level="critical",
+ )
case ["http" | "sse" as transport, port, token]:
build(token).run(
transport,
diff --git a/tests/downstream/smoke_langchain_mcp.py b/tests/downstream/smoke_langchain_mcp.py
new file mode 100644
index 000000000..0bc6dda6d
--- /dev/null
+++ b/tests/downstream/smoke_langchain_mcp.py
@@ -0,0 +1,373 @@
+"""Drive FastMCP through `langchain.mcp`, LangChain's own MCP integration.
+
+`langchain[mcp]` depends on `fastmcp` directly: `MCPAdapter` wraps a
+`fastmcp.Client` or a `fastmcp.client.group.ClientGroup` and turns their tools
+into LangChain tools. This runs in its own environment with the build under
+test, against servers started from the checkout:
+
+ uv build --wheel --out-dir dist . fastmcp_slim
+ uv run --isolated --no-project --no-config --with 'langchain[mcp]' \\
+ --with "fastmcp @ file://$PWD/$(ls dist/fastmcp-4*.whl)" \\
+ --with "fastmcp-slim @ file://$PWD/$(ls dist/fastmcp_slim-*.whl)" \\
+ python tests/downstream/smoke_langchain_mcp.py
+"""
+
+import asyncio
+import os
+import warnings
+from collections.abc import Awaitable, Callable
+from importlib.metadata import version
+from typing import Any
+
+import anyio
+from _harness import (
+ LEGACY_PROXY_GAPS,
+ PROXY_GAPS,
+ TOOLS,
+ Report,
+ quiet,
+ serve,
+ server_env,
+ stdio_command,
+ stdio_transport,
+)
+from langchain.agents import create_agent
+from langchain_core._api import LangChainBetaWarning
+from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
+from langchain_core.messages import AIMessage, ToolMessage
+
+import fastmcp
+from fastmcp.client import Client
+from fastmcp.client.group import ClientGroup
+from fastmcp.mcp_config import MCPConfig
+
+warnings.filterwarnings("ignore", category=LangChainBetaWarning)
+from langchain.mcp import MCPAdapter # noqa: E402
+
+MODERN = "2026-07-28"
+
+
+class ScriptedToolModel(GenericFakeChatModel):
+ def bind_tools(self, tools: Any, **kwargs: Any) -> "ScriptedToolModel":
+ return self
+
+
+def scripted_model(add: str, forecast: str) -> ScriptedToolModel:
+ return ScriptedToolModel(
+ messages=iter(
+ [
+ AIMessage(
+ content="",
+ tool_calls=[
+ {"name": add, "args": {"a": 2, "b": 3}, "id": "call-add"},
+ {
+ "name": forecast,
+ "args": {"city": "Chicago", "days": 2},
+ "id": "call-forecast",
+ },
+ ],
+ ),
+ AIMessage(content="done"),
+ ]
+ )
+ )
+
+
+async def call(tool: Any, args: dict[str, Any]) -> ToolMessage:
+ """Invoke a tool the way an agent does, so the result is a ToolMessage with its artifact."""
+ return await tool.ainvoke(
+ {"type": "tool_call", "name": tool.name, "args": args, "id": "call-1"}
+ )
+
+
+async def accept(message: str, response_type: Any, params: Any, context: Any) -> Any:
+ return {"approved": True}
+
+
+class Observed:
+ """Progress and log notifications a client received."""
+
+ def __init__(self) -> None:
+ self.progress: list[float] = []
+ self.logs: list[str] = []
+
+ async def on_progress(
+ self, value: float, total: float | None, message: str | None
+ ) -> None:
+ self.progress.append(value)
+
+ async def on_log(self, message: Any) -> None:
+ self.logs.append(str(message.data))
+
+ def client(self, target: Any, **kwargs: Any) -> Client[Any]:
+ return Client(
+ target,
+ elicitation_handler=accept,
+ progress_handler=self.on_progress,
+ log_handler=self.on_log,
+ **kwargs,
+ )
+
+
+async def run_checks(
+ report: Report,
+ checks: list[Callable[[], Awaitable[object]]],
+ gaps: dict[str, str] | None = None,
+) -> None:
+ for check in checks:
+ name = check.__name__.replace("_", " ")
+ await report.check(name, check, known_gap=(gaps or {}).get(name))
+
+
+async def exercise(
+ report: Report,
+ target: Any,
+ gaps: dict[str, str] | None = None,
+ **client_kwargs: Any,
+) -> None:
+ seen = Observed()
+ async with MCPAdapter(seen.client(target, **client_kwargs)) as adapter:
+ tools: dict[str, Any] = {}
+
+ async def lists_tools() -> None:
+ tools.update({t.name: t for t in await adapter.list_tools()})
+ assert TOOLS <= set(tools), sorted(tools)
+
+ async def refreshes_tool_list() -> None:
+ refreshed = {t.name for t in await adapter.list_tools(cache_mode="refresh")}
+ assert TOOLS <= refreshed, sorted(refreshed)
+
+ async def server_metadata() -> None:
+ server = tools["add"].metadata["mcp"]["server"]
+ assert server["name"] == "downstream-smoke", server
+
+ async def agent_loop() -> None:
+ agent = create_agent(
+ scripted_model("add", "forecast"), list(tools.values())
+ )
+ state = await agent.ainvoke({"messages": [("user", "add, then forecast")]})
+ returned = {
+ m.name: m.content for m in state["messages"] if m.type == "tool"
+ }
+ assert "5" in str(returned["add"]), returned
+ assert "sunny" in str(returned["forecast"]), returned
+
+ async def structured_output() -> None:
+ message = await call(tools["forecast"], {"city": "Oslo"})
+ expected = {"city": "Oslo", "celsius": 21.5, "conditions": ["sunny"]}
+ assert message.artifact == {"structured_content": expected}, (
+ message.artifact
+ )
+
+ async def float_count_output_schema() -> None:
+ message = await call(tools["stamp"], {})
+ expected = {"when": "2026-09-22T00:00:00Z"}
+ assert message.artifact == {"structured_content": expected}, message
+
+ async def tool_error() -> None:
+ message = await call(tools["divide"], {"a": 1, "b": 0})
+ assert message.status == "error", message
+ assert "divide by zero" in str(message.content), message
+
+ async def image() -> None:
+ [block] = (await call(tools["snapshot"], {})).content
+ assert block["type"] == "image" and block["mime_type"] == "image/png", block
+
+ async def mixed_content() -> None:
+ blocks = (await call(tools["attachments"], {})).content
+ shapes = [(b["type"], b.get("text") or b.get("url")) for b in blocks]
+ assert shapes == [
+ ("text", "see attached"),
+ ("text", "buy milk"),
+ ("file", "config://app"),
+ ], shapes
+
+ async def elicitation() -> None:
+ message = await call(tools["confirm"], {"action": "deploy"})
+ assert "deploy: approved" in str(message.content), message
+
+ async def progress_notifications() -> None:
+ seen.progress.clear()
+ await call(tools["count_to"], {"n": 3})
+ assert seen.progress == [1, 2, 3], seen.progress
+
+ async def logging() -> None:
+ seen.logs.clear()
+ await call(tools["count_to"], {"n": 1})
+ assert any("counted to 1" in line for line in seen.logs), seen.logs
+
+ async def timed_out_call_leaves_connection_usable() -> None:
+ try:
+ with anyio.fail_after(0.5):
+ await call(tools["sleep"], {"seconds": 5})
+ except TimeoutError:
+ pass
+ else:
+ raise AssertionError("sleep(5) finished inside a 0.5s deadline")
+ with anyio.fail_after(10):
+ assert "2" in str((await call(tools["add"], {"a": 1, "b": 1})).content)
+ await anyio.sleep(0.2)
+
+ await run_checks(
+ report,
+ [
+ lists_tools,
+ refreshes_tool_list,
+ server_metadata,
+ agent_loop,
+ structured_output,
+ float_count_output_schema,
+ tool_error,
+ image,
+ mixed_content,
+ elicitation,
+ progress_notifications,
+ logging,
+ timed_out_call_leaves_connection_usable,
+ ],
+ gaps,
+ )
+
+
+async def exercise_group(report: Report, legacy_url: str, token: str) -> None:
+ """One adapter over a ClientGroup: a handshake-era HTTP server and a modern stdio one."""
+ command, args = stdio_command()
+ legacy, modern = Observed(), Observed()
+ group = ClientGroup(
+ {
+ "legacy": legacy.client(legacy_url, auth=token, mode="legacy"),
+ "modern": modern.client(stdio_transport(), mode="auto"),
+ }
+ )
+ async with MCPAdapter(group) as adapter:
+ tools: dict[str, Any] = {}
+
+ async def lists_prefixed_tools() -> None:
+ tools.update({t.name: t for t in await adapter.list_tools()})
+ expected = {
+ f"{server}_{name}" for server in ("legacy", "modern") for name in TOOLS
+ }
+ assert expected <= set(tools), sorted(tools)
+
+ async def each_member_keeps_its_protocol_era() -> None:
+ members = adapter.client.clients # ty: ignore[unresolved-attribute]
+ assert members["legacy"].protocol_version not in (None, MODERN), members
+ assert members["modern"].protocol_version == MODERN, members
+
+ async def agent_loop_across_servers() -> None:
+ model = scripted_model("legacy_add", "modern_forecast")
+ agent = create_agent(model, list(tools.values()))
+ state = await agent.ainvoke({"messages": [("user", "add, then forecast")]})
+ returned = {
+ m.name: m.content for m in state["messages"] if m.type == "tool"
+ }
+ assert "5" in str(returned["legacy_add"]), returned
+ assert "sunny" in str(returned["modern_forecast"]), returned
+
+ async def elicitation_in_both_eras() -> None:
+ for server in ("legacy", "modern"):
+ message = await call(tools[f"{server}_confirm"], {"action": server})
+ assert f"{server}: approved" in str(message.content), (server, message)
+
+ async def calls_route_to_their_own_server() -> None:
+ legacy.progress.clear()
+ modern.progress.clear()
+ await call(tools["modern_count_to"], {"n": 2})
+ assert modern.progress == [1, 2] and legacy.progress == [], (
+ legacy.progress,
+ modern.progress,
+ )
+
+ async def tool_error_from_one_member() -> None:
+ message = await call(tools["legacy_divide"], {"a": 1, "b": 0})
+ assert message.status == "error", message
+
+ await run_checks(
+ report,
+ [
+ lists_prefixed_tools,
+ each_member_keeps_its_protocol_era,
+ agent_loop_across_servers,
+ elicitation_in_both_eras,
+ calls_route_to_their_own_server,
+ tool_error_from_one_member,
+ ],
+ )
+
+
+async def main() -> None:
+ report = Report(
+ "langchain.mcp",
+ {
+ "fastmcp": fastmcp.__version__,
+ "langchain": version("langchain"),
+ "mcp": version("mcp"),
+ },
+ )
+ command, args = stdio_command()
+
+ async def installed_build_is_under_test() -> None:
+ expected = os.environ.get("FASTMCP_EXPECTED_VERSION")
+ assert expected in (None, fastmcp.__version__), (
+ f"expected {expected}, got {fastmcp.__version__}"
+ )
+
+ with report.transport("in-process FastMCP server"):
+ from server import build
+
+ await report.check(
+ "installed build is under test", installed_build_is_under_test
+ )
+ await exercise(report, build())
+
+ with report.transport("stdio"):
+ await exercise(report, stdio_transport())
+
+ with report.transport("MCPConfig"):
+
+ async def adapter_from_config() -> None:
+ config = MCPConfig.from_dict(
+ {
+ "mcpServers": {
+ "smoke": {"command": command, "args": args, "env": server_env()}
+ }
+ }
+ )
+ async with MCPAdapter(config) as adapter:
+ names = {t.name for t in await adapter.list_tools()}
+ assert any(name.endswith("add") for name in names), sorted(names)
+
+ await report.check("adapter from MCPConfig", adapter_from_config)
+
+ for transport, label, client_kwargs, gaps in (
+ ("http", "streamable HTTP", {}, None),
+ ("sse", "SSE", {}, None),
+ ("proxy", "FastMCP proxy", {}, PROXY_GAPS),
+ (
+ "proxy",
+ "FastMCP proxy, handshake-era client",
+ {"mode": "legacy"},
+ LEGACY_PROXY_GAPS,
+ ),
+ ):
+ # The SDK's SSE reader logs a traceback when a check cancels a call on purpose.
+ with (
+ report.transport(label),
+ serve(transport) as server,
+ quiet("mcp.client.sse"),
+ ):
+ await exercise(
+ report, server.url, gaps=gaps, auth=server.token, **client_kwargs
+ )
+
+ with (
+ report.transport("ClientGroup: legacy HTTP + modern stdio"),
+ serve("http") as server,
+ ):
+ await exercise_group(report, server.url, server.token)
+
+ report.finish()
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/tests/downstream/smoke_langchain.py b/tests/downstream/smoke_langchain_mcp_adapters.py
similarity index 79%
rename from tests/downstream/smoke_langchain.py
rename to tests/downstream/smoke_langchain_mcp_adapters.py
index d4bb32917..d14eb48a6 100644
--- a/tests/downstream/smoke_langchain.py
+++ b/tests/downstream/smoke_langchain_mcp_adapters.py
@@ -4,15 +4,25 @@ The adapters pin `mcp<2` while FastMCP 4 needs `mcp>=2`, so they cannot share an
environment. This runs in its own environment against servers started from the
checkout, which also covers handshake-era (mcp v1) clients:
- uv run --isolated --no-project --with langchain-mcp-adapters --with langchain \
- python tests/downstream/smoke_langchain.py
+ uv run --isolated --no-project --no-config --with langchain-mcp-adapters \
+ --with langchain python tests/downstream/smoke_langchain_mcp_adapters.py
"""
import asyncio
from importlib.metadata import version
from typing import Any
-from _harness import INSTRUCTIONS, Report, serve, server_env, stdio_command
+from _harness import (
+ INSTRUCTIONS,
+ LEGACY_PROXY_GAPS,
+ TEMPLATE_READS,
+ TOOLS,
+ Report,
+ quiet,
+ serve,
+ server_env,
+ stdio_command,
+)
from langchain.agents import create_agent
from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
from langchain_core.messages import AIMessage, ToolMessage
@@ -21,17 +31,6 @@ from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain_mcp_adapters.tools import load_mcp_tools
from mcp.types import ElicitResult
-TOOLS = {
- "add",
- "forecast",
- "divide",
- "count_to",
- "snapshot",
- "chime",
- "attachments",
- "confirm",
-}
-
class ScriptedToolModel(GenericFakeChatModel):
def bind_tools(self, tools: Any, **kwargs: Any) -> "ScriptedToolModel":
@@ -66,7 +65,9 @@ async def call(tool: Any, args: dict[str, Any]) -> ToolMessage:
)
-async def exercise(report: Report, connection: dict[str, Any]) -> None:
+async def exercise(
+ report: Report, connection: dict[str, Any], gaps: dict[str, str] | None = None
+) -> None:
progress: list[float] = []
logs: list[str] = []
@@ -145,10 +146,24 @@ async def exercise(report: Report, connection: dict[str, Any]) -> None:
(await call(tools["confirm"], {"action": "deploy"})).content
)
- async def progress_and_logging() -> None:
+ async def progress_notifications() -> None:
+ progress.clear()
assert "counted to 3" in str((await call(tools["count_to"], {"n": 3})).content)
assert progress == [1, 2, 3], progress
- assert any("counted to 3" in line for line in logs), logs
+
+ async def log_messages() -> None:
+ logs.clear()
+ await call(tools["count_to"], {"n": 1})
+ assert any("counted to 1" in line for line in logs), logs
+
+ async def template_literals_and_list_queries() -> None:
+ blobs = await client.get_resources("smoke", uris=list(TEMPLATE_READS))
+ assert [b.as_string() for b in blobs] == list(TEMPLATE_READS.values()), blobs
+
+ async def float_count_output_schema() -> None:
+ message = await call(tools["stamp"], {})
+ expected = {"structured_content": {"when": "2026-09-22T00:00:00Z"}}
+ assert message.artifact == expected, message.artifact
async def explicit_session() -> None:
async with client.session("smoke") as session:
@@ -180,18 +195,22 @@ async def exercise(report: Report, connection: dict[str, Any]) -> None:
image,
mixed_content,
elicitation,
- progress_and_logging,
+ progress_notifications,
explicit_session,
resources,
resource_template,
prompt,
+ template_literals_and_list_queries,
+ float_count_output_schema,
):
- await report.check(check.__name__.replace("_", " "), check)
+ name = check.__name__.replace("_", " ")
+ await report.check(name, check, known_gap=(gaps or {}).get(name))
+ await report.check("logging", log_messages, known_gap=(gaps or {}).get("logging"))
async def main() -> None:
report = Report(
- "langchain",
+ "langchain-mcp-adapters",
{
"langchain-mcp-adapters": version("langchain-mcp-adapters"),
"langchain": version("langchain"),
@@ -213,8 +232,14 @@ async def main() -> None:
for transport, label, kind in (
("http", "streamable HTTP", "streamable_http"),
("sse", "SSE", "sse"),
+ ("proxy", "FastMCP proxy", "streamable_http"),
):
- with report.transport(label), serve(transport) as server:
+ # The SDK's SSE reader logs a traceback when a session closes mid-stream.
+ with (
+ report.transport(label),
+ serve(transport) as server,
+ quiet("mcp.client.sse"),
+ ):
async def rejects_missing_token() -> None:
client = MultiServerMCPClient(
@@ -232,6 +257,7 @@ async def main() -> None:
await exercise(
report,
{"transport": kind, "url": server.url, "headers": server.headers},
+ gaps=LEGACY_PROXY_GAPS if transport == "proxy" else None,
)
report.finish()
diff --git a/tests/downstream/smoke_pydantic_ai.py b/tests/downstream/smoke_pydantic_ai.py
index a0d0d2573..ce9193103 100644
--- a/tests/downstream/smoke_pydantic_ai.py
+++ b/tests/downstream/smoke_pydantic_ai.py
@@ -18,7 +18,19 @@ from importlib.metadata import version
from pathlib import Path
from typing import Any
-from _harness import INSTRUCTIONS, Report, serve, server_env, stdio_command
+import anyio
+from _harness import (
+ INSTRUCTIONS,
+ PROXY_GAPS,
+ TEMPLATE_READS,
+ TOOLS,
+ Report,
+ quiet,
+ serve,
+ server_env,
+ stdio_command,
+ stdio_transport,
+)
from pydantic_ai import Agent, BinaryContent, ModelRetry
from pydantic_ai.mcp import MCPToolset, load_mcp_toolsets
from pydantic_ai.messages import (
@@ -31,18 +43,6 @@ from pydantic_ai.messages import (
from pydantic_ai.models.function import AgentInfo, FunctionModel
import fastmcp
-from fastmcp.client.transports import StdioTransport
-
-TOOLS = {
- "add",
- "forecast",
- "divide",
- "count_to",
- "snapshot",
- "chime",
- "attachments",
- "confirm",
-}
def scripted_model(messages: list[ModelMessage], info: AgentInfo) -> ModelResponse:
@@ -73,7 +73,10 @@ async def accept(
async def exercise(
- report: Report, target: Any, headers: dict[str, str] | None = None
+ report: Report,
+ target: Any,
+ headers: dict[str, str] | None = None,
+ gaps: dict[str, str] | None = None,
) -> None:
progress: list[float] = []
logs: list[str] = []
@@ -144,12 +147,17 @@ async def exercise(
result = await toolset.direct_call_tool("confirm", {"action": "deploy"})
assert result == "deploy: approved", result
- async def progress_and_logging() -> None:
+ async def progress_notifications() -> None:
+ progress.clear()
assert (
await toolset.direct_call_tool("count_to", {"n": 3}) == "counted to 3"
)
assert progress == [1, 2, 3], progress
- assert any("counted to 3" in line for line in logs), logs
+
+ async def log_messages() -> None:
+ logs.clear()
+ await toolset.direct_call_tool("count_to", {"n": 1})
+ assert any("counted to 1" in line for line in logs), logs
async def resources() -> None:
assert "config://app" in {
@@ -168,6 +176,27 @@ async def exercise(
result = await toolset.get_prompt("review", {"code": "x = 1"})
assert "x = 1" in str(result.messages[0].content), result
+ async def template_literals_and_list_queries() -> None:
+ for uri, expected in TEMPLATE_READS.items():
+ assert await toolset.read_resource(uri) == expected, uri
+
+ async def float_count_output_schema() -> None:
+ result = await toolset.direct_call_tool("stamp", {})
+ assert result == {"when": "2026-09-22T00:00:00Z"}, result
+
+ async def timed_out_call_leaves_connection_usable() -> None:
+ with quiet("mcp.client.sse"):
+ try:
+ with anyio.fail_after(0.5):
+ await toolset.direct_call_tool("sleep", {"seconds": 5})
+ except TimeoutError:
+ pass
+ else:
+ raise AssertionError("sleep(5) finished inside a 0.5s deadline")
+ with anyio.fail_after(10):
+ assert await toolset.direct_call_tool("add", {"a": 1, "b": 1}) == 2
+ await anyio.sleep(0.2)
+
for check in (
lists_tools,
instructions,
@@ -178,12 +207,19 @@ async def exercise(
audio,
mixed_content,
elicitation,
- progress_and_logging,
+ progress_notifications,
resources,
resource_template,
prompt,
+ template_literals_and_list_queries,
+ float_count_output_schema,
+ timed_out_call_leaves_connection_usable,
):
- await report.check(check.__name__.replace("_", " "), check)
+ name = check.__name__.replace("_", " ")
+ await report.check(name, check, known_gap=(gaps or {}).get(name))
+ await report.check(
+ "logging", log_messages, known_gap=(gaps or {}).get("logging")
+ )
async def main() -> None:
@@ -207,7 +243,7 @@ async def main() -> None:
await report.check(
"installed build is under test", installed_build_is_under_test
)
- await exercise(report, StdioTransport(command, args, env=server_env()))
+ await exercise(report, stdio_transport())
with tempfile.TemporaryDirectory() as tmp:
config = Path(tmp) / "mcp.json"
@@ -233,8 +269,17 @@ async def main() -> None:
"agent loop from load_mcp_toolsets", agent_loop_from_config
)
- for transport, label in (("http", "streamable HTTP"), ("sse", "SSE")):
- with report.transport(label), serve(transport) as server:
+ for transport, label in (
+ ("http", "streamable HTTP"),
+ ("sse", "SSE"),
+ ("proxy", "FastMCP proxy"),
+ ):
+ # The SDK's SSE reader logs a traceback when a check cancels a call on purpose.
+ with (
+ report.transport(label),
+ serve(transport) as server,
+ quiet("mcp.client.sse"),
+ ):
async def rejects_missing_token() -> None:
try:
@@ -245,7 +290,12 @@ async def main() -> None:
raise AssertionError("connected without a bearer token")
await report.check("rejects missing bearer token", rejects_missing_token)
- await exercise(report, server.url, headers=server.headers)
+ await exercise(
+ report,
+ server.url,
+ headers=server.headers,
+ gaps=PROXY_GAPS if transport == "proxy" else None,
+ )
report.finish()