DSPy: The framework for programming—not prompting—language models
Python
Add Learn MCP page (#8903)
TomuHirata8794f652c873
diff --git a/docs/docs/learn/programming/mcp.md b/docs/docs/learn/programming/mcp.mdnew file mode 100644index 000000000..5667bd071--- /dev/null+++ b/docs/docs/learn/programming/mcp.md@@ -0,0 +1,153 @@+---+sidebar_position: 3+---++# Model Context Protocol (MCP)++The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open protocol that standardizes how applications provide context to language models. DSPy supports MCP, allowing you to use tools from any MCP server with DSPy agents.++## Installation++Install DSPy with MCP support:++```bash+pip install -U "dspy[mcp]"+```++## Overview++MCP enables you to:++- **Use standardized tools** - Connect to any MCP-compatible server.+- **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.++## Using MCP with DSPy++### 1. HTTP Server (Remote)++For remote MCP servers over HTTP, use the streamable HTTP transport:++```python+import asyncio+import dspy+from mcp import ClientSession+from mcp.client.streamable_http import streamablehttp_client++async def main():+ # Connect to HTTP MCP server+ async with streamablehttp_client("http://localhost:8000/mcp") as (read, write):+ async with ClientSession(read, write) as session:+ # Initialize the session+ await session.initialize()++ # List and convert tools+ response = await session.list_tools()+ dspy_tools = [+ dspy.Tool.from_mcp_tool(session, tool)+ for tool in response.tools+ ]++ # Create and use ReAct agent+ class TaskSignature(dspy.Signature):+ task: str = dspy.InputField()+ result: str = dspy.OutputField()++ react_agent = dspy.ReAct(+ signature=TaskSignature,+ tools=dspy_tools,+ max_iters=5+ )++ result = await react_agent.acall(task="Check the weather in Tokyo")+ print(result.result)++asyncio.run(main())+```++### 2. Stdio Server (Local Process)++The most common way to use MCP is with a local server process communicating via stdio:++```python+import asyncio+import dspy+from mcp import ClientSession, StdioServerParameters+from mcp.client.stdio import stdio_client++async def main():+ # Configure the stdio server+ server_params = StdioServerParameters(+ command="python", # Command to run+ args=["path/to/your/mcp_server.py"], # Server script path+ env=None, # Optional environment variables+ )++ # Connect to the server+ async with stdio_client(server_params) as (read, write):+ async with ClientSession(read, write) as session:+ # Initialize the session+ await session.initialize()++ # List available tools+ response = await session.list_tools()++ # Convert MCP tools to DSPy tools+ dspy_tools = [+ dspy.Tool.from_mcp_tool(session, tool)+ for tool in response.tools+ ]++ # Create a ReAct agent with the tools+ class QuestionAnswer(dspy.Signature):+ """Answer questions using available tools."""+ question: str = dspy.InputField()+ answer: str = dspy.OutputField()++ react_agent = dspy.ReAct(+ signature=QuestionAnswer,+ tools=dspy_tools,+ max_iters=5+ )++ # Use the agent+ result = await react_agent.acall(+ question="What is 25 + 17?"+ )+ print(result.answer)++# Run the async function+asyncio.run(main())+```++## Tool Conversion++DSPy automatically handles the conversion from MCP tools to DSPy tools:++```python+# MCP tool from session+mcp_tool = response.tools[0]++# Convert to DSPy tool+dspy_tool = dspy.Tool.from_mcp_tool(session, mcp_tool)++# The DSPy tool preserves:+# - Tool name and description+# - Parameter schemas and types+# - Argument descriptions+# - Async execution support++# Use it like any DSPy tool+result = await dspy_tool.acall(param1="value", param2=123)+```++## Learn More++- [MCP Official Documentation](https://modelcontextprotocol.io/)+- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)+- [DSPy MCP Tutorial](https://dspy.ai/tutorials/mcp/)+- [DSPy Tools Documentation](./tools.md)++MCP integration in DSPy makes it easy to use standardized tools from any MCP server, enabling powerful agent capabilities with minimal setup.diff --git a/docs/mkdocs.yml b/docs/mkdocs.ymlindex c17ed678d..e66539821 100644--- a/docs/mkdocs.yml+++ b/docs/mkdocs.yml@@ -19,6 +19,7 @@ nav:- Modules: learn/programming/modules.md- Adapters: learn/programming/adapters.md- Tools: learn/programming/tools.md+ - MCP: learn/programming/mcp.md- DSPy Evaluation:- Evaluation Overview: learn/evaluation/overview.md- Data Handling: learn/evaluation/data.md