docs(mcp): reduce diff by preserving original comments and structure

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Rehan Ahmed

docs/docs/learn/programming/mcp.md

@@ -20,70 +20,77 @@ 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 minimal setup.
+- **Simplify integration** - Convert MCP tools to DSPy tools with one line.
 
 DSPy provides `stdio_mcp_tools` and `http_mcp_tools` async context managers that handle the full MCP session lifecycle — connecting, initializing, listing tools, and converting them to `dspy.Tool` objects — so you can focus on building your agent.
 
 ## Using MCP with DSPy
 
-### 1. Stdio Server (Local Process)
+### 1. HTTP Server (Remote)
 
-The most common way to use MCP is with a local server process communicating via stdio:
+For remote MCP servers over HTTP, use the streamable HTTP transport:
 
 ```python
 import asyncio
 import dspy
-from mcp import StdioServerParameters
-from dspy.utils.mcp import stdio_mcp_tools
+from dspy.utils.mcp import http_mcp_tools
 
 async def main():
-    server_params = StdioServerParameters(
-        command="python",
-        args=["path/to/your/mcp_server.py"],
-    )
-
-    async with stdio_mcp_tools(server_params) as tools:
-        class QuestionAnswer(dspy.Signature):
-            """Answer questions using available tools."""
-            question: str = dspy.InputField()
-            answer: str = dspy.OutputField()
+    # Connect to HTTP MCP server
+    async with http_mcp_tools("http://localhost:8000/mcp") as tools:
+        # Create and use ReAct agent
+        class TaskSignature(dspy.Signature):
+            task: str = dspy.InputField()
+            result: str = dspy.OutputField()
 
         react_agent = dspy.ReAct(
-            signature=QuestionAnswer,
+            signature=TaskSignature,
             tools=tools,
             max_iters=5,
         )
 
-        result = await react_agent.acall(question="What is 25 + 17?")
-        print(result.answer)
+        result = await react_agent.acall(task="Check the weather in Tokyo")
+        print(result.result)
 
 asyncio.run(main())
 ```
 
-### 2. HTTP Server (Remote)
+### 2. Stdio Server (Local Process)
 
-For remote MCP servers over streamable HTTP:
+The most common way to use MCP is with a local server process communicating via stdio:
 
 ```python
 import asyncio
 import dspy
-from dspy.utils.mcp import http_mcp_tools
+from mcp import StdioServerParameters
+from dspy.utils.mcp import stdio_mcp_tools
 
 async def main():
-    async with http_mcp_tools("http://localhost:8000/mcp") as tools:
-        class TaskSignature(dspy.Signature):
-            task: str = dspy.InputField()
-            result: str = dspy.OutputField()
+    # Configure the stdio server
+    server_params = StdioServerParameters(
+        command="python",                    # Command to run
+        args=["path/to/your/mcp_server.py"], # Server script path
+    )
+
+    # Connect to the server
+    async with stdio_mcp_tools(server_params) as 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=TaskSignature,
+            signature=QuestionAnswer,
             tools=tools,
             max_iters=5,
         )
 
-        result = await react_agent.acall(task="Check the weather in Tokyo")
-        print(result.result)
+        # Use the agent
+        result = await react_agent.acall(question="What is 25 + 17?")
+        print(result.answer)
 
+# Run the async function
 asyncio.run(main())
 ```
 

docs/docs/tutorials/mcp/index.md

@@ -293,9 +293,9 @@ create a file named `dspy_mcp_agent.py`, and follow the guide to add code to it.
 ### Gather Tools from MCP Servers
 
 We first need to gather all available tools from the MCP server and make them
-usable by DSPy. DSPy provides `stdio_mcp_tools` which handles the entire MCP session
-lifecycle — connecting, initializing, listing tools, and converting them to
-[`dspy.Tool`](https://dspy.ai/api/primitives/Tool/) objects:
+usable by DSPy. DSPy provides an API [`dspy.Tool`](https://dspy.ai/api/primitives/Tool/)
+as the standard tool interface. The `stdio_mcp_tools` helper handles the entire MCP session
+lifecycle — connecting, initializing, listing tools, and converting them to `dspy.Tool`:
 
 ```python
 from mcp import StdioServerParameters
@@ -305,6 +305,7 @@ from dspy.utils.mcp import stdio_mcp_tools
 server_params = StdioServerParameters(
     command="python",  # Executable
     args=["path_to_your_working_directory/mcp_server.py"],
+    env=None,
 )
 
 async def run():
@@ -318,7 +319,8 @@ if __name__ == "__main__":
     asyncio.run(run())
 ```
 
-With the code above, we have successfully collected all available MCP tools as DSPy tools.
+With the code above, we have successfully collected all available MCP tools and converted
+them to DSPy tools.
 
 
 ### Build a DSPy Agent to Handle Customer Requests
@@ -363,8 +365,9 @@ from dspy.utils.mcp import stdio_mcp_tools
 
 # Create server parameters for stdio connection
 server_params = StdioServerParameters(
-    command="python",
-    args=["path_to_your_working_directory/mcp_server.py"],
+    command="python",  # Executable
+    args=["script_tmp/mcp_server.py"],  # Optional command line arguments
+    env=None,  # Optional environment variables
 )
 
 
@@ -386,7 +389,9 @@ dspy.configure(lm=dspy.LM("openai/gpt-4o-mini"))
 
 async def run(user_request):
     async with stdio_mcp_tools(server_params) as tools:
+        # Create the agent
         react = dspy.ReAct(DSPyAirlineCustomerService, tools=tools)
+
         result = await react.acall(user_request=user_request)
         print(result)