docs: fix duplicate args and add Returns/Example to mcp() tool helper

src/xai_sdk/tools.py

@@ -266,17 +266,32 @@ def mcp(
 ) -> chat_pb2.Tool:
     """Creates a server-side tool for connecting to a remote MCP server, typically used in agentic requests.
 
-    This tool enables the model to call tools on a remote MCP server
+    This tool enables the model to call tools on a remote MCP server.
 
     Args:
         server_url: The URL of the MCP server.
         server_label: Optional label of the MCP server. This will be used to prefix tool names if provided.
         server_description: Optional description of the MCP server.
-        server_label: The label of the MCP server. This will be used to prefix tool names if provided.
-        server_description: The description of the MCP server.
-        allowed_tool_names: The names of the tools that the model is allowed to call. If empty, all tools are allowed.
-        authorization: The authorization token for the MCP server.
-        extra_headers: The extra headers for the MCP server.
+        allowed_tool_names: Optional list of tool names that the model is allowed to call. If omitted,
+            all tools exposed by the MCP server are allowed.
+        authorization: Optional authorization token for the MCP server.
+        extra_headers: Optional extra headers to send to the MCP server.
+
+    Returns:
+        A `chat_pb2.Tool` object configured for the MCP server.
+
+    Example:
+        ```
+        from xai_sdk.tools import mcp
+
+        # Create an MCP tool that connects to a remote MCP server
+        tool = mcp(
+            server_url="https://mcp.example.com",
+            server_label="example",
+            allowed_tool_names=["search", "lookup"],
+            authorization="Bearer my-token",
+        )
+        ```
     """
     return chat_pb2.Tool(
         mcp=chat_pb2.MCP(

tests/chat_test.py

@@ -661,6 +661,44 @@ def test_server_side_tool_image_search_enum():
     assert usage_pb2.ServerSideTool.Name(usage_pb2.SERVER_SIDE_TOOL_IMAGE_SEARCH) == "SERVER_SIDE_TOOL_IMAGE_SEARCH"
 
 
+def test_mcp_tool_minimal():
+    """Test that mcp() creates a tool with only server_url set."""
+    from xai_sdk.tools import mcp
+
+    tool = mcp(server_url="https://mcp.example.com")
+
+    assert isinstance(tool, chat_pb2.Tool)
+    assert tool.HasField("mcp")
+    assert tool.mcp.server_url == "https://mcp.example.com"
+    assert tool.mcp.server_label == ""
+    assert tool.mcp.server_description == ""
+    assert list(tool.mcp.allowed_tool_names) == []
+    assert tool.mcp.authorization == ""
+    assert dict(tool.mcp.extra_headers) == {}
+
+
+def test_mcp_tool_all_fields():
+    """Test that mcp() correctly sets every field on the MCP proto."""
+    from xai_sdk.tools import mcp
+
+    tool = mcp(
+        server_url="https://mcp.example.com",
+        server_label="example",
+        server_description="An example MCP server",
+        allowed_tool_names=["search", "lookup"],
+        authorization="Bearer my-token",
+        extra_headers={"X-Trace-Id": "abc123"},
+    )
+
+    assert tool.HasField("mcp")
+    assert tool.mcp.server_url == "https://mcp.example.com"
+    assert tool.mcp.server_label == "example"
+    assert tool.mcp.server_description == "An example MCP server"
+    assert list(tool.mcp.allowed_tool_names) == ["search", "lookup"]
+    assert tool.mcp.authorization == "Bearer my-token"
+    assert dict(tool.mcp.extra_headers) == {"X-Trace-Id": "abc123"}
+
+
 def test_developer_message():
     """Test that developer() creates a message with ROLE_DEVELOPER role."""
     # Simple string content