OpenAI Agents SDK #28：HostedMCPTool 完全拆解——HostedTool 家族第三成员，2 个外层参数 + 6 个 tool_config 字段

MCP 在 SDK 里的两条路

async with MCPServerSse(
    name="My SSE Server",
    params={"url": "https://example.com/sse"}
) as server:
    agent = Agent(
        name="Assistant",
        instructions="Use the tools to achieve the task",
        mcp_servers=[server]
    )

from agents import Agent, Runner, HostedMCPTool

tool = HostedMCPTool(
    tool_config={
        "type": "mcp",
        "server_label": "my_service",
        "server_url": "https://example.com/mcp",
        "require_approval": "never"
    }
)

agent = Agent(
    name="Assistant",
    tools=[tool]
)

HostedMCPTool 的完整参数

tool_config 的 6 个字段

require_approval：人在回路的开关

from agents import (
    Agent, Runner, HostedMCPTool,
    MCPToolApprovalRequest, MCPToolApprovalFunctionResult
)
import os

# 安全操作：直接放行；危险操作：拦截
SAFE_TOOLS = {"list_tasks", "get_project", "read_file"}
RESTRICTED_TOOLS = {"delete_task", "delete_project", "write_file"}

def approve_tool_call(
    request: MCPToolApprovalRequest
) -> MCPToolApprovalFunctionResult:
    tool_name = request.data.name
    if tool_name in SAFE_TOOLS:
        return {"approve": True}
    elif tool_name in RESTRICTED_TOOLS:
        return {"approve": False, "reason": "写入/删除操作需要人工确认"}
    else:
        # 未知工具：默认拒绝
        return {"approve": False, "reason": f"未知工具 {tool_name}，需人工审核"}

tool = HostedMCPTool(
    tool_config={
        "type": "mcp",
        "server_label": "file_service",
        "server_url": "https://example.com/mcp",
        "headers": {"Authorization": f"Bearer {os.getenv('API_TOKEN')}"},
        "require_approval": "always"
    },
    on_approval_request=approve_tool_call
)

allowed_tools：比 require_approval 更彻底的限制

tool = HostedMCPTool(
    tool_config={
        "type": "mcp",
        "server_label": "task_service",
        "server_url": "https://example.com/mcp",
        "headers": {"X-API-KEY": os.getenv("TASK_API_KEY")},
        "allowed_tools": [
            "list_tasks",
            "get_task",
            "create_task",
            # 故意排除 delete_task 和 update_task
        ],
        "require_approval": "never"
    }
)

• 多租户系统：不同 Agent 对同一 MCP 服务器有不同权限边界
• 只读 Agent：只暴露 list_ / get_ 前缀的工具，屏蔽所有写操作
• Token 节约：MCP 服务器工具数量大时，只暴露当前任务需要的工具子集，减少 schema 的 token 占用

headers：认证字段的设计约束

HostedMCPTool vs 两种本地 MCP 方式的横向对比

一个完整示例：带认证和工具白名单的任务管理 Agent

import os
from agents import Agent, Runner, HostedMCPTool

taskmaster_tool = HostedMCPTool(
    tool_config={
        "type": "mcp",
        "server_label": "taskmaster",
        "server_url": "https://example-mcp-service.com/mcp",
        "headers": {
            "Authorization": f"Bearer {os.getenv('MCP_API_TOKEN')}"
        },
        "allowed_tools": [
            "list_projects",
            "get_project",
            "list_tasks",
            "create_task",
            "update_task"
        ],
        "require_approval": "never"
    }
)

agent = Agent(
    name="Task Manager",
    instructions=(
        "你是一个任务管理助手。帮助用户查看和管理项目与任务。"
        "不要主动删除任何内容，除非用户明确要求。"
    ),
    tools=[taskmaster_tool]
)

result = Runner.run_sync(agent, "帮我看一下当前有哪些进行中的项目")
print(result.final_output)

三条生产级实践建议