From f9971afd14665b3e7071c82e92bfc93c9fce2d70 Mon Sep 17 00:00:00 2001
From: Kropiunig <kropiunig@csh.ac.at>
Date: Tue, 26 May 2026 06:16:40 +0200
Subject: [PATCH] docs: fix duplicate args and add Returns/Example to mcp()
 tool helper

The mcp() docstring listed `server_label` and `server_description` twice,
omitted the `Returns:` section, missed the `Example:` section that every
other helper in `tools.py` provides, and was missing a trailing period.
Deduplicate the Args block, add a Returns/Example block matching the
surrounding helpers, and add unit tests covering the minimal and full
field paths through the helper.
---
 src/xai_sdk/tools.py | 27 +++++++++++++++++++++------
 tests/chat_test.py   | 38 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 59 insertions(+), 6 deletions(-)

diff --git a/src/xai_sdk/tools.py b/src/xai_sdk/tools.py
index a5c8701..97cdc89 100644
--- a/src/xai_sdk/tools.py
+++ b/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(
diff --git a/tests/chat_test.py b/tests/chat_test.py
index 1db217d..19ee040 100644
--- a/tests/chat_test.py
+++ b/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