Skip to content

armgit / dspy

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.yml
index 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