工具

远程 MCP 工具

远程 MCP 工具允许 Grok 连接到外部 MCP（模型上下文协议）服务器，通过来自第三方或您自己实现的自定义工具扩展其功能。只需指定服务器 URL 和可选配置 - xAI 将为您管理 MCP 服务器的连接和交互。

SDK 支持

远程 MCP 工具在 xAI 原生 SDK、OpenAI 兼容的 Responses API 和语音转语音 API 中得到支持。

NOTE

OpenAI Responses API 中的 require_approval 和 connector_id 参数目前不支持。

配置

要使用远程 MCP 工具，您需要在请求的工具数组中配置到您 MCP 服务器的连接。

参数	必需	描述
`server_url`	是	要连接的 MCP 服务器 URL。仅支持流式 HTTP 和 SSE 传输。
`server_label`	是	用于标识服务器的标签（用于工具调用前缀）
`server_description`	否	对服务器提供内容的描述
`allowed_tools`	否	允许的特定工具名称列表（空列表表示允许所有工具）。xAI 原生 SDK 使用参数名 `allowed_tool_names`。
`authorization`	否	将在向 MCP 服务器发送的请求的 Authorization 标头中设置的令牌
`headers`	否	要包含在请求中的附加标头。xAI 原生 SDK 使用参数名 `extra_headers`。

基本 MCP 工具使用

python

import os

from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import mcp

client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(
    model="grok-4.5",
    tools=[
        mcp(server_url="https://mcp.deepwiki.com/mcp"),
    ],
    include=["verbose_streaming"],
)

chat.append(user("What can you do with https://github.com/xai-org/xai-sdk-python?"))

is_thinking = True
for response, chunk in chat.stream():
    # View the server-side tool calls as they are being made in real-time
    for tool_call in chunk.tool_calls:
        print(f"\\nCalling tool: {tool_call.function.name} with arguments: {tool_call.function.arguments}")
    if response.usage.reasoning_tokens and is_thinking:
        print(f"\\rThinking... ({response.usage.reasoning_tokens} tokens)", end="", flush=True)
    if chunk.content and is_thinking:
        print("\\n\\nFinal Response:")
        is_thinking = False
    if chunk.content and not is_thinking:
        print(chunk.content, end="", flush=True)

print("\\n\\nUsage:")
print(response.usage)
print(response.server_side_tool_usage)
print("\\n\\nServer Side Tool Calls:")
print(response.tool_calls)

python

import os
from openai import OpenAI

api_key = os.getenv("XAI_API_KEY")
client = OpenAI(
    api_key=api_key,
    base_url="https://api.x.ai/v1",
)

response = client.responses.create(
    model="grok-4.5",
    input=[
        {
            "role": "user",
            "content": "What can you do with https://github.com/xai-org/xai-sdk-python?",
        },
    ],
    tools=[
        {
            "type": "mcp",
            "server_url": "https://mcp.deepwiki.com/mcp",
            "server_label": "deepwiki",
        }
    ],
)

print(response)

python

import os
import requests

url = "https://api.x.ai/v1/responses"
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.getenv('XAI_API_KEY')}"
}
payload = {
    "model": "grok-4.5",
    "input": [
        {
            "role": "user",
            "content": "What can you do with https://github.com/xai-org/xai-sdk-python?"
        }
    ],
    "tools": [
        {
            "type": "mcp",
            "server_url": "https://mcp.deepwiki.com/mcp",
            "server_label": "deepwiki",
        }
    ]
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())

bash

curl https://api.x.ai/v1/responses \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $XAI_API_KEY" \\
  -d '{
  "model": "grok-4.5",
  "input": [
    {
      "role": "user",
      "content": "What can you do with https://github.com/xai-org/xai-sdk-python?"
    }
  ],
  "tools": [
    {
        "type": "mcp",
        "server_url": "https://mcp.deepwiki.com/mcp",
        "server_label": "deepwiki"
    }
  ]
}'

工具启用和访问控制

当您配置远程 MCP 工具时未指定 allowed_tools，MCP 服务器公开的所有工具定义将自动注入到模型的上下文中。这意味着模型可以访问 MCP 服务器提供的每个工具，允许它在对话期间使用其中任何一个。

例如，如果一个 MCP 服务器公开了 10 个不同的工具，而您没有指定 allowed_tools，所有 10 个工具定义将对模型可用。然后，模型可以根据用户请求和工具描述选择调用其中任何一个工具。

使用 allowed_tools 参数来有选择地仅启用来自 MCP 服务器的特定工具。这可以给您带来几个关键好处：

更好的性能：通过限制模型需要考虑的工具定义来减少上下文开销
降低风险：例如，限制仅执行只读操作的工具的访问，以防止模型修改数据

python

# Enable only specific tools from a server with many available tools
mcp(
    server_url="https://comprehensive-tools.example.com/mcp",
    allowed_tool_names=["search_database", "format_data"]
)

这种方法不是让模型访问服务器提供的每个工具，而是使 Grok 保持专注和高效，同时确保它拥有所需的确切功能。

多服务器支持

同时启用多个 MCP 服务器，以创建丰富的专业工具生态系统：

python

chat = client.chat.create(
    model="grok-4.5",
    tools=[
        mcp(server_url="https://mcp.deepwiki.com/mcp", server_label="deepwiki"),
        mcp(server_url="https://your-custom-tools.com/mcp", server_label="custom"),
        mcp(server_url="https://api.example.com/tools", server_label="api-tools"),
    ],
)

每个服务器可以提供不同的功能 - 文档工具、API 集成、自定义业务逻辑或专业数据处理 - 所有功能都在单个对话中可访问。

最佳实践

提供清晰的服务器元数据：配置多个 MCP 服务器时，使用描述性的 server_label 和 server_description，以帮助模型理解每个服务器的目的并选择正确的工具
适当过滤工具：使用 allowed_tools 将访问权限限制在仅必要的工具上，特别是当服务器有许多工具时，因为模型必须将所有可用的工具定义保存在上下文中
使用安全连接：始终使用 HTTPS URL，并在您的 MCP 服务器上实施适当的身份验证机制
提供示例：虽然模型通常可以根据工具描述和用户请求确定使用哪些工具，但在提示中提供示例可能会有所帮助

工具 ​

远程 MCP 工具 ​

SDK 支持 ​

配置 ​

基本 MCP 工具使用 ​

工具启用和访问控制 ​

多服务器支持 ​

最佳实践 ​

工具

远程 MCP 工具

SDK 支持

配置

基本 MCP 工具使用

工具启用和访问控制

多服务器支持

最佳实践