Skip to content

armgit / dspy

Public Imported from GitHub
0

DSPy: The framework for programming—not prompting—language models

Python

feat: support MCP SDK v2 without changing result semantics (#10188)

Isaac Miller32bcd36ce6d9
diff --git a/.github/workflows/run_tests.yml b/.github/workflows/run_tests.yml
index c057afc69..66ac09778 100644
--- a/.github/workflows/run_tests.yml
+++ b/.github/workflows/run_tests.yml
@@ -133,6 +133,34 @@ jobs:
- name: Run extra and deno tests
run: uv run -p .venv pytest tests/ -m 'extra or deno' --extra --deno -n auto --dist worksteal
+ mcp_v2_test:
+ name: Run MCP v2 Tests
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ steps:
+ - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+ with:
+ persist-credentials: false
+ - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+ with:
+ python-version: "3.11"
+ - name: Install uv with caching
+ uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+ with:
+ enable-cache: true
+ cache-dependency-glob: |
+ **/pyproject.toml
+ **/uv.lock
+ - name: Create environment
+ run: uv venv .venv
+ - name: Install dependencies with MCP v2
+ run: |
+ uv sync -p .venv --extra dev
+ uv pip install -p .venv "mcp==2.0.0"
+ - name: Run MCP tests
+ run: uv run --frozen --no-sync -p .venv pytest tests/utils/test_mcp.py -m extra --extra
+
llm_call_test:
name: Run Tests with Real LM
runs-on: ubuntu-latest
diff --git a/docs/docs/diving-deeper/tools-react-and-mcp.md b/docs/docs/diving-deeper/tools-react-and-mcp.md
index 2e4a7c1cd..42a8cfe32 100644
--- a/docs/docs/diving-deeper/tools-react-and-mcp.md
+++ b/docs/docs/diving-deeper/tools-react-and-mcp.md
@@ -107,7 +107,7 @@ Constructor helper. Builds a `ToolCalls` from a list of `{"name", "args"}` dicts
### MCP bridge
**`dspy.utils.mcp.convert_mcp_tool(session, tool)`** → `Tool`
-Builds a `Tool` whose `func` is an `async def` closure: it awaits `session.call_tool(tool.name, arguments=kwargs)` and unpacks the result. The unpacker pulls text from any `TextContent` entries (returning a single string when there’s one, a list otherwise) and returns non-text entries as-is. An `isError=True` response raises `RuntimeError`. The MCP tool’s `inputSchema` is mapped to DSPy’s `args`/`arg_types`/`arg_desc` via `convert_input_schema_to_tool_args`.
+Builds a `Tool` whose `func` is an `async def` closure: it awaits `session.call_tool(tool.name, arguments=kwargs)` and unpacks the result. The bridge supports the camelCase fields in mcp SDK v1 and their snake_case replacements in v2. An error result raises `RuntimeError`; text and non-text content retain their existing behavior. The tool’s input schema is mapped to DSPy’s `args`/`arg_types`/`arg_desc` via `convert_input_schema_to_tool_args`.
**`dspy.utils.mcp.convert_input_schema_to_tool_args(schema)`** → `(args, arg_types, arg_desc)`
Walks an MCP-style JSON schema and produces the three dicts a `Tool` needs. Resolves `$defs`, picks up `description` fields as `arg_desc`, and translates JSON-schema types to Python types via a `_TYPE_MAPPING` table. Exported in case callers want to write their own bridge against a non-MCP protocol with similar JSON-schema arguments.
diff --git a/docs/docs/learn/programming/mcp.md b/docs/docs/learn/programming/mcp.md
index 5667bd071..6da07ccc2 100644
--- a/docs/docs/learn/programming/mcp.md
+++ b/docs/docs/learn/programming/mcp.md
@@ -22,13 +22,28 @@ MCP enables you to:
- **Share tools across stacks** - Use the same tools across different frameworks.
- **Simplify integration** - Convert MCP tools to DSPy tools with one line.
-DSPy does not handle MCP server connections directly. You can use client interfaces of the `mcp` library to establish the connection and pass `mcp.ClientSession` to `dspy.Tool.from_mcp_tool` in order to convert mcp tools into DSPy tools.
+DSPy does not handle MCP server connections directly. Use a client interface from the `mcp` library, then pass the client or session to `dspy.Tool.from_mcp_tool`. DSPy supports both major versions of the `mcp` Python SDK.
## Using MCP with DSPy
### 1. HTTP Server (Remote)
-For remote MCP servers over HTTP, use the streamable HTTP transport:
+With `mcp` SDK v2, use the high-level `Client` for a remote server:
+
+```python
+import asyncio
+import dspy
+from mcp.client import Client
+
+async def main():
+ async with Client("http://localhost:8000/mcp") as client:
+ response = await client.list_tools()
+ dspy_tools = [dspy.Tool.from_mcp_tool(client, tool) for tool in response.tools]
+
+asyncio.run(main())
+```
+
+With SDK v1, use the streamable HTTP transport and a `ClientSession`:
```python
import asyncio
@@ -69,7 +84,7 @@ asyncio.run(main())
### 2. Stdio Server (Local Process)
-The most common way to use MCP is with a local server process communicating via stdio:
+The most common way to use MCP is with a local server process communicating via stdio. This example works with both SDK versions:
```python
import asyncio
diff --git a/docs/docs/tutorials/mcp/index.md b/docs/docs/tutorials/mcp/index.md
index 2a5171915..a794c4472 100644
--- a/docs/docs/tutorials/mcp/index.md
+++ b/docs/docs/tutorials/mcp/index.md
@@ -46,11 +46,15 @@ it:
import random
import string
-from mcp.server.fastmcp import FastMCP
from pydantic import BaseModel
+try:
+ from mcp.server.fastmcp import FastMCP as MCPServer # SDK v1
+except ImportError:
+ from mcp.server import MCPServer # SDK v2
+
# Create an MCP server
-mcp = FastMCP("Airline Agent")
+mcp = MCPServer("Airline Agent")
class Date(BaseModel):
@@ -220,10 +224,10 @@ if __name__ == "__main__":
Before we start the server, let's take a look at the code.
-We first create a `FastMCP` instance, which is a utility that helps quickly build an MCP server:
+We first create a server instance, using the class name provided by the installed SDK version:
```python
-mcp = FastMCP("Airline Agent")
+mcp = MCPServer("Airline Agent")
```
Then we define our data structures, which in a real-world application would be the database schema, e.g.:
diff --git a/dspy/adapters/types/tool.py b/dspy/adapters/types/tool.py
index ff2bc37b4..0aac2dd27 100644
--- a/dspy/adapters/types/tool.py
+++ b/dspy/adapters/types/tool.py
@@ -1,6 +1,6 @@
import asyncio
import inspect
-from typing import TYPE_CHECKING, Any, Callable, get_origin, get_type_hints
+from typing import TYPE_CHECKING, Any, Callable, Protocol, get_origin, get_type_hints
import json_repair
import pydantic
@@ -18,6 +18,10 @@ if TYPE_CHECKING:
_TYPE_MAPPING = {"string": str, "integer": int, "number": float, "boolean": bool, "array": list, "object": dict}
+class _MCPToolClient(Protocol):
+ async def call_tool(self, name: str, arguments: dict[str, Any] | None = None) -> Any: ...
+
+
class Tool(Type):
"""Tool class.
@@ -200,12 +204,12 @@ class Tool(Type):
return result
@classmethod
- def from_mcp_tool(cls, session: "mcp.ClientSession", tool: "mcp.types.Tool") -> "Tool":
+ def from_mcp_tool(cls, session: _MCPToolClient, tool: "mcp.types.Tool") -> "Tool":
"""
- Build a DSPy tool from an MCP tool and a ClientSession.
+ Build a DSPy tool from an MCP tool and a compatible MCP client.
Args:
- session: The MCP session to use.
+ session: An MCP client or session with an async ``call_tool`` method.
tool: The MCP tool to convert.
Returns:
diff --git a/dspy/utils/mcp.py b/dspy/utils/mcp.py
index 288c056ab..82802e206 100644
--- a/dspy/utils/mcp.py
+++ b/dspy/utils/mcp.py
@@ -1,11 +1,19 @@
from typing import TYPE_CHECKING, Any
-from dspy.adapters.types.tool import Tool, convert_input_schema_to_tool_args
+from dspy.adapters.types.tool import Tool, _MCPToolClient, convert_input_schema_to_tool_args
if TYPE_CHECKING:
import mcp
+def _get_field(obj: Any, snake_name: str, camel_name: str, default: Any = None) -> Any:
+ """Read a field whose Python name changed between mcp SDK v1 and v2."""
+ for name in (snake_name, camel_name):
+ if hasattr(obj, name):
+ return getattr(obj, name)
+ return default
+
+
def _convert_mcp_tool_result(call_tool_result: "mcp.types.CallToolResult") -> str | list[Any]:
from mcp.types import TextContent
@@ -21,23 +29,27 @@ def _convert_mcp_tool_result(call_tool_result: "mcp.types.CallToolResult") -> st
if len(text_contents) == 1:
tool_content = tool_content[0]
- if call_tool_result.isError:
+ if _get_field(call_tool_result, "is_error", "isError", default=False):
raise RuntimeError(f"Failed to call a MCP tool: {tool_content}")
return tool_content or non_text_contents
-def convert_mcp_tool(session: "mcp.ClientSession", tool: "mcp.types.Tool") -> Tool:
+def convert_mcp_tool(session: _MCPToolClient, tool: "mcp.types.Tool") -> Tool:
"""Build a DSPy tool from an MCP tool.
+ Both mcp SDK v1's ``ClientSession`` and v2's high-level ``Client`` satisfy
+ the client interface used by this bridge.
+
Args:
- session: The MCP session to use.
+ session: An MCP client or session with an async ``call_tool`` method.
tool: The MCP tool to convert.
Returns:
A dspy Tool object.
"""
- args, arg_types, arg_desc = convert_input_schema_to_tool_args(tool.inputSchema)
+ input_schema = _get_field(tool, "input_schema", "inputSchema", default={})
+ args, arg_types, arg_desc = convert_input_schema_to_tool_args(input_schema)
# Convert the MCP tool and Session to a single async method
async def func(*args, **kwargs):
diff --git a/tests/utils/resources/mcp_server.py b/tests/utils/resources/mcp_server.py
index c40ad737d..64addc9b0 100644
--- a/tests/utils/resources/mcp_server.py
+++ b/tests/utils/resources/mcp_server.py
@@ -1,7 +1,11 @@
-from mcp.server.fastmcp import FastMCP
from pydantic import BaseModel
-mcp = FastMCP("test")
+try:
+ from mcp.server.fastmcp import FastMCP as MCPServer
+except ImportError:
+ from mcp.server import MCPServer
+
+mcp = MCPServer("test")
class Profile(BaseModel):
diff --git a/tests/utils/test_mcp.py b/tests/utils/test_mcp.py
index 9bcdc1e48..5ccbdb891 100644
--- a/tests/utils/test_mcp.py
+++ b/tests/utils/test_mcp.py
@@ -1,21 +1,72 @@
import asyncio
import importlib
+import sys
+from importlib.metadata import version
+from types import SimpleNamespace
import pytest
-from dspy.utils.mcp import convert_mcp_tool
+from dspy import Tool
+from dspy.utils.mcp import _convert_mcp_tool_result, convert_mcp_tool
if importlib.util.find_spec("mcp") is None:
pytest.skip(reason="mcp is not installed", allow_module_level=True)
+def make_call_tool_result(field_style, texts=(), is_error=False):
+ from mcp.types import TextContent
+
+ fields = {
+ "content": [TextContent(type="text", text=text) for text in texts],
+ "structured_content" if field_style == "snake" else "structuredContent": {"result": "ignored"},
+ "is_error" if field_style == "snake" else "isError": is_error,
+ }
+ return SimpleNamespace(**fields)
+
+
+def test_convert_mcp_tool_result_supports_both_field_styles_without_changing_results():
+ assert _convert_mcp_tool_result(make_call_tool_result("camel", texts=["hi"])) == "hi"
+ assert _convert_mcp_tool_result(make_call_tool_result("snake", texts=["a", "b"])) == ["a", "b"]
+
+
[email protected]("field_style", ["camel", "snake"])
+def test_error_result_raises(field_style):
+ result = make_call_tool_result(field_style, texts=["boom"], is_error=True)
+ with pytest.raises(RuntimeError, match="Failed to call a MCP tool: boom"):
+ _convert_mcp_tool_result(result)
+
+
+async def test_convert_mcp_tool_with_v2_client():
+ if int(version("mcp").split(".")[0]) < 2:
+ pytest.skip("The high-level MCP client is available in SDK v2")
+
+ from mcp.client import Client
+ from mcp.server import MCPServer
+
+ server = MCPServer("test")
+
+ @server.tool()
+ def increment(value: int) -> int:
+ return value + 1
+
+ async with Client(server) as client:
+ response = await client.list_tools()
+ increment_tool = Tool.from_mcp_tool(client, response.tools[0])
+ assert await increment_tool.acall(value=1) == "2"
+
+
@pytest.mark.asyncio
@pytest.mark.extra
async def test_convert_mcp_tool():
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
+
server_params = StdioServerParameters(
- command="python",
+ command=sys.executable,
args=["tests/utils/resources/mcp_server.py"],
env=None,
)
@@ -28,7 +79,10 @@ async def test_convert_mcp_tool():
add_tool = convert_mcp_tool(session, response.tools[0])
assert add_tool.name == "add"
assert add_tool.desc == "Add two numbers"
- assert add_tool.args == {"a": {"title": "A", "type": "integer"}, "b": {"title": "B", "type": "integer"}}
+ assert add_tool.args == {
+ "a": {"title": "A", "type": "integer"},
+ "b": {"title": "B", "type": "integer"},
+ }
assert add_tool.arg_types == {"a": int, "b": int}
assert add_tool.arg_desc == {
"a": "No description provided. (Required)",
@@ -49,9 +103,7 @@ async def test_convert_mcp_tool():
error_tool = convert_mcp_tool(session, response.tools[2])
assert error_tool.name == "wrong_tool"
assert error_tool.desc == "This tool raises an error"
- with pytest.raises(
- RuntimeError, match="Failed to call a MCP tool: Error executing tool wrong_tool: error!"
- ):
+ with pytest.raises(RuntimeError, match="error!"):
await error_tool.acall()
# Check nested Pydantic arg