Repository navigation
Commit 280442b
Adds `langchain.mcp`: adapt an MCP server into LangChain tools ready for
`create_agent`.
```python
from langchain.agents import create_agent
from langchain.mcp import MCPAdapter
adapter = MCPAdapter("https://example.com/mcp")
agent = create_agent("anthropic:claude-sonnet-5", await adapter.list_tools())
```
`langchain-mcp-adapters` stays the place for the full surface
(interceptors, callbacks, prompts, resources). This is the short path
for the common case.
## Public API
`MCPAdapter(target, *, elicitation=None)`, with a `client` property,
`list_tools(*, cache_mode="use")`, and async context management.
`as_langchain_tool(tool, client, *, elicitation=None)` converts a single
tool for callers managing their own client.
`MCPAdapter` accepts anything `fastmcp.Client` accepts — a URL, `Path`,
in-process server, `ClientTransport`, `MCPConfig` (or its dict form), or
a pre-built `Client` — plus a FastMCP `ClientGroup` for a fleet of
servers behind one client. Inference is FastMCP's, so new target types
work without changes here. The target union is `MCPAdapterTarget`; it is
not part of the package's public surface (it is only useful for
annotating a `target`), but it stays importable from
`langchain.mcp.adapter` for that purpose. An `MCPConfig` naming several
servers yields one prefixed toolset from one adapter:
```python
MCPAdapter({"mcpServers": {"notes": {"command": "python", "args": ["notes.py"]},
"web": {"url": "https://example.com/mcp"}}})
# -> ["notes_read_note", "web_get_weather", ...]
```
## Tool conversion
Tool results are ported from `langchain-mcp-adapters`, so a call reaches
a model in the same shape either way. Results become LangChain content
blocks (audio raises `NotImplementedError`); structured content becomes
an `MCPToolArtifact`; `args_schema` is the tool's `input_schema`.
Tool *metadata* is grouped under a single `mcp` namespace so a consumer
can tell an MCP tool's provenance apart and keep tool-level fields
distinct from the serving server's identity:
```python
tool.metadata == {
"mcp": {
"tool": {
"annotations": {"destructive_hint": True, ...}, # snake_case, from tool.annotations
"_meta": {...}, # verbatim MCP `_meta`
},
"server": {"name": "files", "version": "2.1.0", ...}, # from the live client connection
},
}
```
Server identity comes off the connection (a `Tool` carries no server
field) and is read at conversion time while the client is connected.
This metadata rides onto the LangChain tool's `metadata`, so it also
lands on the tool's traced run — `mcp.server.name` becomes filterable in
traces. The examples PR uses the destructive hint to gate a tool behind
human approval.
An `isError=True` result becomes a `ToolMessage` with `status="error"`
carrying the server's own error content, so the agent can correct itself
instead of the run ending. Transport failures and unconvertible content
still raise.
FastMCP clients are reentrant and reference-counted, so the adapter adds
no second layer — tools hold the client and stay callable after the
adapter's context exits.
## Discovery caching
`list_tools(cache_mode=...)` selects how discovery interacts with the
client-side response cache (SEP-2549): `use` (default) serves a cached
tool list within the server's TTL hint, `refresh` calls the server and
repopulates it, `bypass` skips the cache. The cache and its
per-principal isolation are configured on the client itself
(`Client(cache=...)`); this only selects how discovery reads it. The
default is `use` so a configured cache is honored — note this differs
from a bare `ClientGroup.list_tools()`, whose own default is `refresh`.
## Elicitation
Some MCP tools need input before they can finish.
`elicitation="interrupt"` surfaces the question as a LangGraph
interrupt:
```python
adapter = MCPAdapter(server, elicitation="interrupt")
paused = await agent.ainvoke({"messages": [...]}, config)
[question] = paused["__interrupt__"][0].value["requests"]
# {'key': 'date', 'message': 'What date would you like to book?', 'mode': 'form',
# 'requested_schema': {...}}
await agent.ainvoke(
Command(resume={"responses": {question["key"]: {"action": "accept", "content": {"date": "2026-08-26"}}}}),
config,
)
```
Answers correlate by the server's own request keys, so nothing extra is
needed on resume. Several requests in one round share one interrupt;
successive rounds each get their own. The payload types live in
`langchain.mcp.elicitation`, split so the type system carries the
protocol's rules: `mode` discriminates form from URL requests, and only
an accept can carry content, narrowed to the scalar shapes the wire
accepts.
It is opt-in because a declared capability is a promise on the wire —
servers only build flows that depend on it once a client says yes — so
left unset, a server whose tool *requires* an answer refuses the call
rather than running without one. The loop is driven through
`session.call_tool(..., allow_input_required=True)` rather than a
FastMCP handler, which would convert the `GraphInterrupt` into an MCP
error. Resuming re-issues the call from its first round, since the
interrupt unwound it; a server that asks before doing work repeats
nothing, which the tests assert by counting tool-body executions.
Scope is elicitation only. Embedded sampling and roots requests raise,
since driving the loop by hand bypasses the FastMCP callbacks that
answer them, as does a continuation round carrying only `request_state`
— that is the protocol's long-running-work channel, and serving it would
mean polling a remote server from inside a tool call.
## Building on FastMCP
Handing the client to FastMCP is what keeps this small. Most of the
protocol surface is inherited rather than written:
- **Negotiation, per server.** FastMCP speaks both the 2025-11-25
`initialize` handshake and the 2026-07-28 `server/discover` revision,
and picks per connection — so one agent can hold tools from servers on
different revisions at once, with no protocol mode to choose. There is a
test that builds exactly that agent.
- **Transports and auth.** Inference covers URLs, script paths,
in-process servers, and config dicts, while `auth="oauth"`, bearer
tokens, custom `httpx` auth, and TLS via `verify` all arrive without
code here.
- **Fleets.** A `ClientGroup` target lets one adapter serve a fleet of
servers, prefixing each server's tools and routing every call back to
the client that serves it.
- **Connection lifecycle.** Clients are reentrant and reference-counted,
so tools outlive the adapter's context without a second layer of
bookkeeping, and requests race the background session task so a dead
HTTP session raises instead of hanging a tool call.
- **The input-required flow (SEP-2322).** Elicitation intercepts a round
at the session layer instead of reimplementing the multi-round protocol.
- **In-process servers.** The whole unit suite drives real MCP servers
with no subprocess and no socket.
This requires `fastmcp>=4.0.0` — the GA line whose multi-server config
routes to modern-protocol servers, which the `MCPConfig` and
`ClientGroup` support rely on.
## Release note
New `langchain.mcp` namespace. `MCPAdapter` adapts any target
`fastmcp.Client` accepts — a URL, a local script, an in-process server,
an `MCPConfig` naming several servers, or a pre-built client — as well
as a FastMCP `ClientGroup`, into LangChain tools ready for
`create_agent`. `MCPAdapter.list_tools(cache_mode=...)` discovers tools
with optional client-side response caching. `as_langchain_tool` converts
a single MCP tool for callers managing their own client. Tool metadata
(annotations, `_meta`, and the serving server's identity) is grouped
under an `mcp` namespace on each tool. `elicitation="interrupt"`
surfaces a server's mid-call questions as LangGraph interrupts. Requires
the `mcp` extra: `pip install "langchain[mcp]"`.
## Notes for review
- A `Path` or script-path target launches a local subprocess with no
opt-in keyword. Intended, and the target comes from application code
rather than a model, but it loosens the previous default and is awkward
to walk back once released.
- Tool metadata is traced. Whatever a server puts in `_meta` reaches the
tool's LangSmith run verbatim; keeping it nested under `mcp.tool._meta`
(rather than flattened) keeps that clearly demarcated.
- Two FastMCP internals are load-bearing, and both now fail loudly
rather than silently. `elicitation="interrupt"` installs a sentinel
handler purely to trip the SDK's identity comparison against its default
callback, which is the only way the SDK lets a client declare the
capability; a test asserts the negotiated capability so a change
upstream cannot quietly stop servers asking. `_await_monitored` reaches
for FastMCP's private `_await_with_session_monitoring`, without which a
session dying mid-elicitation hangs the tool call; the fallback now
warns.
- `tests/unit_tests/mcp/conftest.py` grants `blockbuster` two narrow
allowances, both caused upstream in FastMCP: entering a server `Context`
resolves an optional dependency through `importlib.metadata` on every
in-process request, and `mcp.client.session` imports `jsonschema` lazily
on first tool call.
---
*Prepared with the assistance of an AI agent.*
---------
Signed-off-by: Hunter Lovell <[email protected]>
Co-authored-by: Hunter Lovell <[email protected]>
Co-authored-by: Hunter Lovell <[email protected]>
Co-authored-by: Sydney Runkle <[email protected]>
1 parent f5ee2b6 commit 280442b
15 files changed
Lines changed: 3855 additions & 22 deletions
File tree
- libs/langchain_v1
- langchain
- mcp
- tests
- integration_tests/mcp
- unit_tests/mcp
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | | - | |
| 3 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| 120 | + | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
| 126 | + | |
| 127 | + | |
| 128 | + | |
| 129 | + | |
| 130 | + | |
| 131 | + | |
| 132 | + | |
| 133 | + | |
| 134 | + | |
| 135 | + | |
| 136 | + | |
| 137 | + | |
| 138 | + | |
| 139 | + | |
| 140 | + | |
| 141 | + | |
| 142 | + | |
| 143 | + | |
| 144 | + | |
| 145 | + | |
| 146 | + | |
| 147 | + | |
| 148 | + | |
| 149 | + | |
| 150 | + | |
| 151 | + | |
| 152 | + | |
| 153 | + | |
| 154 | + | |
| 155 | + | |
| 156 | + | |
| 157 | + | |
| 158 | + | |
| 159 | + | |
| 160 | + | |
| 161 | + | |
| 162 | + | |
| 163 | + | |
| 164 | + | |
| 165 | + | |
| 166 | + | |
| 167 | + | |
| 168 | + | |
| 169 | + | |
| 170 | + | |
| 171 | + | |
| 172 | + | |
| 173 | + | |
| 174 | + | |
| 175 | + | |
| 176 | + | |
| 177 | + | |
| 178 | + | |
| 179 | + | |
| 180 | + | |
| 181 | + | |
| 182 | + | |
| 183 | + | |
| 184 | + | |
| 185 | + | |
| 186 | + | |
| 187 | + | |
| 188 | + | |
| 189 | + | |
| 190 | + | |
| 191 | + | |
| 192 | + | |
| 193 | + | |
| 194 | + | |
| 195 | + | |
| 196 | + | |
| 197 | + | |
| 198 | + | |
| 199 | + | |
| 200 | + | |
| 201 | + | |
| 202 | + | |
| 203 | + | |
| 204 | + | |
| 205 | + | |
| 206 | + | |
| 207 | + | |
| 208 | + | |
| 209 | + | |
| 210 | + | |
| 211 | + | |
| 212 | + | |
| 213 | + | |
| 214 | + | |
| 215 | + | |
| 216 | + | |
| 217 | + | |
| 218 | + | |
| 219 | + | |
| 220 | + | |
| 221 | + | |
| 222 | + | |
| 223 | + | |
| 224 | + | |
| 225 | + | |
| 226 | + | |
| 227 | + | |
| 228 | + | |
| 229 | + | |
| 230 | + | |
| 231 | + | |
| 232 | + | |
| 233 | + | |
| 234 | + | |
| 235 | + | |
| 236 | + | |
| 237 | + | |
| 238 | + | |
| 239 | + | |
| 240 | + | |
| 241 | + | |
| 242 | + | |
| 243 | + | |
| 244 | + | |
| 245 | + | |
0 commit comments