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.ymlindex 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 testsrun: 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 LMruns-on: ubuntu-latestdiff --git a/docs/docs/diving-deeper/tools-react-and-mcp.md b/docs/docs/diving-deeper/tools-react-and-mcp.mdindex 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.mdindex 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`:```pythonimport 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:```pythonimport asynciodiff --git a/docs/docs/tutorials/mcp/index.md b/docs/docs/tutorials/mcp/index.mdindex 2a5171915..a794c4472 100644--- a/docs/docs/tutorials/mcp/index.md+++ b/docs/docs/tutorials/mcp/index.md@@ -46,11 +46,15 @@ it:import randomimport string-from mcp.server.fastmcp import FastMCPfrom 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.pyindex ff2bc37b4..0aac2dd27 100644--- a/dspy/adapters/types/tool.py+++ b/dspy/adapters/types/tool.py@@ -1,6 +1,6 @@import asyncioimport 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_hintsimport json_repairimport 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.pyindex 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_argsif 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") -> stif 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 methodasync def func(*args, **kwargs):diff --git a/tests/utils/resources/mcp_server.py b/tests/utils/resources/mcp_server.pyindex 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 FastMCPfrom 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.pyindex 9bcdc1e48..5ccbdb891 100644--- a/tests/utils/test_mcp.py+++ b/tests/utils/test_mcp.py@@ -1,21 +1,72 @@import asyncioimport importlib+import sys+from importlib.metadata import version+from types import SimpleNamespaceimport pytest-from dspy.utils.mcp import convert_mcp_tool+from dspy import Tool+from dspy.utils.mcp import _convert_mcp_tool_result, convert_mcp_toolif 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.extraasync def test_convert_mcp_tool():from mcp import ClientSession, StdioServerParametersfrom 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