Skip to content

Commit 8330dfe

Browse files
sydney-runklehntrlSydney Runkle
authored
docs(langchain): runnable langchain.mcp examples (#39976)
Stacked on #39939 — review that first; this branch adds only `libs/langchain_v1/examples/mcp/`. Ten self-contained scripts, one idea each. Every one starts whatever MCP server it needs, so `uv run examples/mcp/<name>.py` is the whole workflow. | Example | Shows | Model | Network | |---|---|:-:|:-:| | `transports.py` | one adapter over in-memory, stdio, and HTTP | | | | `remote_server.py` | pointing the adapter at a public MCP server | ✅ | ✅ | | `multi_server.py` | several servers behind one adapter, tools prefixed per server | ✅ | | | `graph_factory.py` | one per-user MCP fleet behind a `langgraph dev` graph factory | ✅ | | | `protocol_eras.py` | one agent holding tools from both MCP protocol eras | ✅ | | | `tool_errors.py` | a failing tool reaching the model so it can retry | ✅ | | | `elicitation.py` | a server asking a human mid-call, via `interrupt()` | ✅ | | | `destructive_interrupt.py` | gating destructive tools behind approval, from tool metadata | ✅ | | | `auth_bearer.py` | a server behind a static bearer token | | | | `auth_oauth.py` | a full OAuth 2.1 flow with dynamic client registration | | | Each was run against a real model (or a real `langgraph dev` server) before committing, and its output is what the docstring claims. A few choices worth knowing about: - **Servers come from FastMCP's own `run_server_in_process`**, not hand-rolled uvicorn plumbing, so the examples teach the adapter rather than how to start a server. - **HTTP appears only where it is the subject.** `multi_server.py` names its backends over stdio, which is less machinery and a better illustration, since a fleet addresses each backend independently. - **`remote_server.py` hits DeepWiki**, a public MCP server, where the URL is the entire configuration. It prints the tool call so the answer is visibly the remote server's work rather than the model's memory. - **`tool_errors.py` pins the model with a system prompt.** Without it the model answers the arithmetic from memory and the error path never runs. - **`destructive_interrupt.py` derives the approval gate from metadata**, reading each tool's `metadata["mcp"]["tool"]["annotations"]["destructive_hint"]` to build the `HumanInTheLoopMiddleware` `interrupt_on` map — so any tool a server flags as destructive pauses for approval, no tool names hardcoded. - **`auth_oauth.py` opens a browser tab.** The demo authorization server auto-approves, so it redirects straight back — but it is the one example that cannot run unattended. `graph_factory.py` is registered by a `langgraph.json` and run under `langgraph dev` rather than invoked directly. It shows a per-user MCP fleet: one shared `httpx` connection pool for everyone, a per-user `ClientGroup` built each run, and per-user discovery caching keyed on the caller's identity read off the injected `ServerRuntime`. `run_graph_factory_demo.py` is an end-to-end driver that stands up two guarded MCP servers plus a `langgraph dev` server with custom auth and runs the graph once per user; `auth.py`, `langgraph.json`, and `_fleet_servers.py` support it. `_servers.py` holds the small MCP servers the examples share, `_stdio_server.py` is the entry point launched as a subprocess over stdio, and neither `_`-prefixed helper is part of the API being demonstrated. `examples/*` picks up the same two ruff exemptions `scripts/*` already has, for printing and for not being a package. ## Release note No library changes — examples only. --- *Prepared with the assistance of an AI agent.* --------- Co-authored-by: Hunter Lovell <[email protected]> Co-authored-by: Hunter Lovell <[email protected]> Co-authored-by: Sydney Runkle <[email protected]>
1 parent 280442b commit 8330dfe

18 files changed

Lines changed: 1064 additions & 0 deletions
Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# `langchain.mcp` examples
2+
3+
Runnable, self-contained scripts. Each starts whatever MCP server it needs, so
4+
there is nothing to launch separately.
5+
6+
```bash
7+
uv sync --extra mcp --extra anthropic
8+
export ANTHROPIC_API_KEY=... # needed by the examples that run an agent
9+
uv run examples/mcp/transports.py
10+
```
11+
12+
| Example | Shows | Model | Network |
13+
|---|---|:-:|:-:|
14+
| `transports.py` | one adapter over in-memory, stdio, and HTTP | | |
15+
| `remote_server.py` | pointing the adapter at a public MCP server | ✅ | ✅ |
16+
| `multi_server.py` | several servers behind one adapter, tools prefixed per server | ✅ | |
17+
| `graph_factory.py` | one long-lived adapter shared by every run of a `langgraph dev` graph | | |
18+
| `protocol_eras.py` | one agent holding tools from both MCP protocol eras | ✅ | |
19+
| `tool_errors.py` | a failing tool reaching the model so it can retry | ✅ | |
20+
| `elicitation.py` | a server asking a human mid-call, via `interrupt()` | ✅ | |
21+
| `destructive_interrupt.py` | gating destructive tools behind approval, from tool metadata | ✅ | |
22+
| `auth_bearer.py` | a server behind a static bearer token | | |
23+
| `auth_oauth.py` | a full OAuth 2.1 flow with dynamic client registration | | |
24+
25+
`remote_server.py` calls DeepWiki, a public MCP server, so it needs internet
26+
access. `auth_oauth.py` opens a browser tab; the demo authorization server
27+
auto-approves, so it redirects straight back.
28+
29+
`_servers.py` holds the small MCP servers the examples share, and
30+
`_stdio_server.py` is the entry point launched as a subprocess over stdio.
31+
Neither is part of the API being demonstrated.
Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
"""Run the two guarded MCP servers the graph factory talks to.
2+
3+
`graph_factory.py` points `SERVERS` at fixed ports; this starts a server on
4+
each. Both verify tokens against the shared keypair (`MCP_DEMO_KEYFILE`), the
5+
same one `langgraph dev` mints with, so a token minted in the factory process
6+
validates here.
7+
8+
MCP_DEMO_KEYFILE=/path/to/keys.json uv run examples/mcp/_fleet_servers.py
9+
"""
10+
11+
from __future__ import annotations
12+
13+
import multiprocessing
14+
15+
from _servers import PUBLIC_KEY, run_guarded_server
16+
17+
PORTS = {"calendar": 8001, "docs": 8002}
18+
19+
20+
def main() -> None:
21+
procs = [
22+
multiprocessing.Process(
23+
target=run_guarded_server,
24+
args=("127.0.0.1", port, name, PUBLIC_KEY),
25+
daemon=True,
26+
)
27+
for name, port in PORTS.items()
28+
]
29+
for proc in procs:
30+
proc.start()
31+
for proc in procs:
32+
proc.join()
33+
34+
35+
if __name__ == "__main__":
36+
main()
Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
"""Tiny MCP servers the examples share, so each example stays about one idea.
2+
3+
Nothing here is specific to LangChain — these are plain FastMCP servers. The
4+
`run_*` functions exist because a server reached over stdio or HTTP has to be
5+
started as its own process, and that entry point cannot be a lambda.
6+
"""
7+
8+
from __future__ import annotations
9+
10+
import json
11+
import os
12+
from pathlib import Path
13+
14+
from fastmcp import Context, FastMCP
15+
from fastmcp.server.auth.providers.jwt import JWTVerifier, RSAKeyPair
16+
from fastmcp.server.dependencies import get_access_token
17+
from mcp.types import (
18+
ElicitRequest,
19+
ElicitRequestFormParams,
20+
ElicitResult,
21+
InputRequiredResult,
22+
TextContent,
23+
ToolAnnotations,
24+
)
25+
from pydantic import SecretStr
26+
27+
28+
def weather_server() -> FastMCP[None]:
29+
"""A server with one tool that always succeeds."""
30+
mcp: FastMCP[None] = FastMCP("weather")
31+
32+
@mcp.tool
33+
def get_forecast(city: str) -> str:
34+
"""Report the forecast for a city."""
35+
return f"{city}: 18C and clear."
36+
37+
return mcp
38+
39+
40+
def calculator_server() -> FastMCP[None]:
41+
"""A server whose tool reports failure for input it cannot handle."""
42+
mcp: FastMCP[None] = FastMCP("calculator")
43+
44+
@mcp.tool
45+
def divide(numerator: float, denominator: float) -> str:
46+
"""Divide two numbers."""
47+
if denominator == 0:
48+
# Raising inside a tool becomes an MCP error result (`isError=True`)
49+
# rather than a transport failure, which is what lets the agent see
50+
# it and retry. See `tool_errors.py`.
51+
msg = "Cannot divide by zero. Choose a non-zero denominator."
52+
raise ValueError(msg)
53+
return str(numerator / denominator)
54+
55+
return mcp
56+
57+
58+
def files_server() -> FastMCP[None]:
59+
"""A server with a read-only tool and a destructive one.
60+
61+
`delete_file` sets `destructiveHint=True`; the adapter surfaces that as
62+
`metadata["mcp"]["tool"]["annotations"]["destructive_hint"]`, which
63+
`destructive_interrupt.py` uses to gate the tool behind human approval.
64+
"""
65+
mcp: FastMCP[None] = FastMCP("files")
66+
67+
@mcp.tool
68+
def list_files() -> list[str]:
69+
"""List the files in the workspace."""
70+
return ["report.md", "notes.txt"]
71+
72+
@mcp.tool(annotations=ToolAnnotations(destructiveHint=True))
73+
def delete_file(path: str) -> str:
74+
"""Delete a file from the workspace."""
75+
return f"Deleted {path}."
76+
77+
return mcp
78+
79+
80+
def booking_server() -> FastMCP[None]:
81+
"""A server whose tool cannot finish without an answer from a human.
82+
83+
Uses the guard pattern: the tool checks whether the answer it needs has
84+
arrived and, if not, returns an `InputRequiredResult` describing the
85+
question instead of doing any work. Returning early is what makes the call
86+
safe to replay when the run resumes.
87+
"""
88+
mcp: FastMCP[None] = FastMCP("booking")
89+
90+
@mcp.tool
91+
async def book_table(party_size: int, ctx: Context) -> list[TextContent] | InputRequiredResult:
92+
"""Book a restaurant table. Asks the user which date to book."""
93+
answers = ctx.input_responses
94+
if not answers or "date" not in answers:
95+
return InputRequiredResult(
96+
input_requests={
97+
"date": ElicitRequest(
98+
method="elicitation/create",
99+
params=ElicitRequestFormParams(
100+
mode="form",
101+
message="What date would you like to book?",
102+
requested_schema={
103+
"type": "object",
104+
"properties": {"date": {"type": "string", "format": "date"}},
105+
"required": ["date"],
106+
},
107+
),
108+
)
109+
},
110+
request_state="awaiting-date",
111+
)
112+
113+
answer = answers["date"]
114+
if not isinstance(answer, ElicitResult) or answer.action != "accept" or not answer.content:
115+
return [TextContent(type="text", text="No date given, so nothing was booked.")]
116+
date = answer.content["date"]
117+
return [TextContent(type="text", text=f"Booked a table for {party_size} on {date}.")]
118+
119+
return mcp
120+
121+
122+
def run_weather_stdio() -> None:
123+
"""Entry point for a weather server spoken to over stdio."""
124+
weather_server().run()
125+
126+
127+
def run_calculator_stdio() -> None:
128+
"""Entry point for a calculator server spoken to over stdio."""
129+
calculator_server().run()
130+
131+
132+
def run_weather_http(host: str, port: int) -> None:
133+
"""Entry point for a weather server served over HTTP."""
134+
weather_server().run(
135+
transport="http", host=host, port=port, show_banner=False, log_level="warning"
136+
)
137+
138+
139+
def run_calculator_http(host: str, port: int) -> None:
140+
"""Entry point for a calculator server served over HTTP."""
141+
calculator_server().run(
142+
transport="http", host=host, port=port, show_banner=False, log_level="warning"
143+
)
144+
145+
146+
ISSUER = "https://demo.issuer"
147+
AUDIENCE = "mcp-fleet"
148+
149+
150+
def _load_or_generate_keys() -> RSAKeyPair:
151+
"""Return one keypair shared across processes, or a fresh one per process.
152+
153+
A single process (the `run_server_in_process` examples) can generate its
154+
own keypair and pass its public half to the server. A multi-process demo
155+
cannot: the `langgraph dev` worker that mints tokens and the server process
156+
that verifies them are different interpreters. Point both at the same PEM
157+
file via `MCP_DEMO_KEYFILE` and they share one keypair; leave it unset and
158+
every process keeps its own, exactly as before.
159+
"""
160+
keyfile = os.environ.get("MCP_DEMO_KEYFILE")
161+
if keyfile:
162+
data = json.loads(Path(keyfile).read_text())
163+
return RSAKeyPair(private_key=SecretStr(data["private_key"]), public_key=data["public_key"])
164+
return RSAKeyPair.generate()
165+
166+
167+
_KEYS = _load_or_generate_keys()
168+
"""Stands in for an identity provider, so the examples can mint real tokens."""
169+
170+
PUBLIC_KEY = _KEYS.public_key
171+
"""Pass this to `run_guarded_server`; see why in its docstring."""
172+
173+
174+
def token_for(user: str) -> str:
175+
"""Mint an access token identifying `user`.
176+
177+
The stand-in for whatever a deployment already has: an OAuth gateway that
178+
exchanges for a per-user token, or a provider from `fastmcp.client.auth` —
179+
`OAuth(mcp_url=..., token_storage=<per-user store>)` runs the full
180+
authorization-code flow per identity, which `auth_oauth.py` demonstrates.
181+
"""
182+
return _KEYS.create_token(subject=user, issuer=ISSUER, audience=AUDIENCE)
183+
184+
185+
def run_guarded_server(host: str, port: int, name: str, public_key: str) -> None:
186+
"""Serve a token-guarded server whose one tool reports who called it.
187+
188+
The key is a parameter rather than read from this module: the server runs
189+
in its own process, which re-imports this file and would otherwise mint a
190+
second, unrelated key pair.
191+
"""
192+
mcp: FastMCP[None] = FastMCP(
193+
name,
194+
auth=JWTVerifier(public_key=public_key, issuer=ISSUER, audience=AUDIENCE),
195+
# Opt into client-side response caching (SEP-2549): the server stamps
196+
# each cacheable result with this TTL and a `private` scope, so a client
197+
# holding a `CacheConfig` can serve a repeat `tools/list` from its own
198+
# store instead of the wire. Without these hints the server sends
199+
# `ttlMs: 0` and nothing caches, which is why arbitrary third-party
200+
# servers cannot be relied on for this.
201+
cache_ttl=60,
202+
cache_scope="private",
203+
)
204+
205+
@mcp.tool
206+
def whoami() -> str:
207+
"""Report the identity the server derived from the access token."""
208+
token = get_access_token()
209+
return "unauthenticated" if token is None else str(token.claims.get("sub"))
210+
211+
mcp.run(transport="http", host=host, port=port, show_banner=False, log_level="warning")
Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
"""Run one of the shared servers over stdio, chosen by argv.
2+
3+
`MCPAdapter` launches this as a subprocess; it is not part of the API being
4+
demonstrated.
5+
"""
6+
7+
import sys
8+
9+
from _servers import run_calculator_stdio, run_weather_stdio
10+
11+
if __name__ == "__main__":
12+
which = sys.argv[1] if len(sys.argv) > 1 else "weather"
13+
(run_calculator_stdio if which == "calculator" else run_weather_stdio)()
Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
"""Custom auth so `langgraph dev` knows which user a run belongs to.
2+
3+
The handler maps the `x-user-id` header to a user identity. That identity is
4+
what `graph_factory.make_graph` reads off `runtime.user` and mints an MCP token
5+
for, so each run talks to the fleet as its own user. A real deployment
6+
validates a credential against an identity provider and returns the user it
7+
resolves to; here the header is trusted directly, which is enough to
8+
demonstrate per-user routing. (`x-api-key` is reserved by the LangGraph SDK for
9+
its own auth, so the demo uses a different header.)
10+
11+
Wired in via `langgraph.json`.
12+
"""
13+
14+
from __future__ import annotations
15+
16+
from langgraph_sdk import Auth
17+
18+
auth = Auth()
19+
20+
21+
@auth.authenticate
22+
async def authenticate(headers: dict) -> Auth.types.MinimalUserDict:
23+
"""Resolve the caller from `x-user-id`, rejecting requests without one."""
24+
user_id = headers.get(b"x-user-id")
25+
if not user_id:
26+
raise Auth.exceptions.HTTPException(status_code=401, detail="Missing x-user-id")
27+
identity = user_id.decode() if isinstance(user_id, bytes) else str(user_id)
28+
return {"identity": identity}
Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
"""A server behind a static bearer token.
2+
3+
The simple end of MCP auth: the server never issues credentials, it only
4+
verifies the token arriving in `Authorization: Bearer <token>`. No discovery,
5+
no browser, no refresh — you provisioned the token out of band and the client
6+
presents it.
7+
8+
uv run examples/mcp/auth_bearer.py
9+
"""
10+
11+
from __future__ import annotations
12+
13+
import asyncio
14+
15+
from fastmcp import FastMCP
16+
from fastmcp.client import Client
17+
from fastmcp.server.auth.providers.jwt import StaticTokenVerifier
18+
from fastmcp.utilities.tests import run_server_in_process
19+
20+
from langchain.mcp import MCPAdapter
21+
22+
TOKEN = "demo-weather-token" # noqa: S105
23+
24+
25+
def run_guarded_server(host: str, port: int) -> None:
26+
"""Serve a weather server that only answers callers presenting `TOKEN`."""
27+
# Demo only — `StaticTokenVerifier` holds tokens in plaintext memory. A real
28+
# deployment uses `JWTVerifier` against an IdP's JWKS, or OAuth (see
29+
# `auth_oauth.py`).
30+
mcp: FastMCP[None] = FastMCP(
31+
"weather",
32+
auth=StaticTokenVerifier(tokens={TOKEN: {"client_id": "demo", "scopes": ["read"]}}),
33+
)
34+
35+
@mcp.tool
36+
def get_forecast(city: str) -> str:
37+
"""Report the forecast for a city."""
38+
return f"{city}: 18C and clear."
39+
40+
mcp.run(transport="http", host=host, port=port, show_banner=False, log_level="warning")
41+
42+
43+
async def main() -> None:
44+
"""Call the guarded server with, and without, the token."""
45+
with run_server_in_process(run_guarded_server) as url:
46+
# `auth` takes a bearer token string, the literal "oauth", or any
47+
# `httpx2.Auth`. A config dict takes the same key per server.
48+
async with MCPAdapter(Client(f"{url}/mcp", auth=TOKEN)) as adapter:
49+
[forecast] = await adapter.list_tools()
50+
[block] = await forecast.ainvoke({"city": "Oslo"})
51+
print("with token: ", block["text"])
52+
53+
try:
54+
async with MCPAdapter(f"{url}/mcp") as adapter:
55+
await adapter.list_tools()
56+
except Exception as exc:
57+
print("without token:", type(exc).__name__)
58+
59+
60+
if __name__ == "__main__":
61+
asyncio.run(main())

0 commit comments

Comments
 (0)