企业官网建设流程全解析

如果你正在用 OpenHands Software Agent SDK 构建 AI Agent，那么集成 MCP（Model Context Protocol）协议是让你的智能体接入任意外部工具生态的关键一步。本教程面向新手，讲清楚 OpenHands SDK 是如何原生支持 MCP 的：从连接本地命令行工具，到对接远程 Notion、GitHub 等 OAuth 服务，再到用 Agent Server 一键校验 MCP 配置，帮你用最短路径把外部工具变成 Agent 能直接调用的能力。

🤔 为什么你的 AI Agent 需要 MCP？

想象一下：你的 Agent 已经会读写文件、执行终端命令了，但它还不会查 GitHub Issue、不会搜索网页、不会整理 Notion 笔记。MCP 协议解决的就是这个问题——它为"AI 应用 ↔ 外部工具/数据"定义了一套标准接口：

• MCP Server：把某个工具或数据源（网页抓取、代码仓库打包、Notion API……）封装成标准服务
• MCP Client：AI Agent 端负责连接服务、发现工具并发起调用
• 好处：一次接入，生态复用。全球已有大量现成的 MCP Server，你的 Agent 无需为每个工具单独写适配代码

OpenHands Software Agent SDK 把这套能力做成了声明式配置：你只要在创建 Agent 时传入一个mcp_config字典，MCP Server 暴露的工具就会自动注入 Agent 的工具列表，LLM 会像使用内置工具一样自然地调用它们。

📦 SDK 中的 MCP 集成架构

MCP 相关代码集中在 openhands-sdk/openhands/sdk/mcp/ 目录，各文件职责清晰：

入口很简洁：所有组件从 mcp/init.py 统一导出，例如MCPServer、MCPClient、create_mcp_tools。

🚀 三步接入本地 MCP Server（stdio 方式）

最常见的场景是运行一个本地命令行 MCP Server（通过uvx/npx等即时启动）。官方示例 07_mcp_integration.py 演示了完整流程，核心代码只有三行配置：

from openhands.sdk import Agent, Conversation from openhands.sdk.mcp import MCPServer mcp_config = { "fetch": MCPServer(command="uvx", args=["--with", "mcp==1.29.0", "mcp-server-fetch==2026.7.10"]), "repomix": MCPServer(command="npx", args=["-y", "repomix@1.4.2", "--mcp"]), } agent = Agent(llm=llm, tools=tools, mcp_config=mcp_config)

随后Conversation(agent=agent)正常运行，LLM 就能调用fetch抓取的网页内容和repomix的代码打包能力。stdio 类型的服务器只需要command和args，SDK 会自动管理子进程的启动与关闭（连接封装见 client.py）。

🔌 连接远程 MCP Server 与五种认证方式

云端服务（如 Notion 官方 MCP 端点）使用 HTTP 类传输。MCPServer支持四种传输协议：stdio、http、streamable-http、sse（定义见 config.py 中的MCPTransport）。

以官方示例 08_mcp_with_oauth.py 接入 Notion 为例：

mcp_config = { "Notion": MCPServer( url="https://mcp.notion.com/mcp", auth=MCPOAuthAuthCredential(strategy="oauth2"), ) }

对于非 OAuth 的服务，auth字段还支持以下策略（均为config.py中的 Pydantic 模型）：

所有密钥字段都用 Pydantic 的SecretStr承载，序列化时默认自动脱敏（REDACTED_SECRET_VALUE），避免 API Key 意外出现在日志或配置导出中——这是 config.py 中大量field_serializer的核心用意。

✂️ 用 filter_tools_regex 精准筛选 MCP 工具

接入一个"全家桶"式 MCP Server 时，工具可能太多，既浪费 Token 又容易让 LLM 选错工具。OpenHands 提供了filter_tools_regex参数，按名称正则过滤：

agent = Agent( llm=llm, mcp_config=mcp_config, filter_tools_regex="^(?!repomix)(.*)|^repomix.*pack_codebase.*$", )

上面的正则把repomix服务器里除pack_codebase之外的工具全部屏蔽，只保留最需要的一个（参数定义见 agent/base.py）。这个过滤发生在所有内置工具与 MCP 工具装配完成之后，对两类工具统一生效。

此外，MCPServer还有enabled开关：设为false的服务器会保留完整配置（包括密钥），但在创建 MCP 工具和转发给 ACP 子进程时都会被跳过，方便临时停用某个服务。

✅ 保存配置前先校验：Agent Server 的 MCP 测试端点

配置写错了怎么办？远端 MCP Server 的鉴权问题往往要到工具真正执行时才暴露（比如 Slack MCP 用错 token 也能连上）。为此，Agent Server 提供了专门的隔离校验端点，实现位于 mcp_router.py：

curl -X POST http://localhost:8000/api/mcp/test \ -H "Content-Type: application/json" \ -d '{"url": "https://mcp.notion.com/mcp", "transport": "http", "auth": {"strategy": "oauth2"}}'

该端点会临时建立连接、列出服务器宣称的全部工具、可选地真实调用一个只读工具验证凭据，然后干净地拆除连接，全程不修改任何已保存的设置。对于 OAuth 服务器，探测过程中拿到的 token 会返回在响应的oauth_state字段，可直接持久化。TypeScript 客户端也暴露了对应的 settings API（createMcpServer/patchMcpServer/deleteMcpServer，见 clients/typescript/README.md），让"添加新 MCP 服务器"成为一次带校验的表单操作，而不是猜着填配置。

🔒 安全设计：MCP 集成中的防线

面向生产环境时，有几个值得知道的安全细节：

• 敏感值全链路保护：env、headers、auth中的密钥字段均为SecretStr，API 响应默认脱敏，仅本地调试可显式取明文
• 重定向头泄露防护：通过 utils.py 中的_PackageRemoteMCPServer，配置在插件包里的远程服务器如果发生跨域重定向，其自定义请求头会被自动剥离，防止凭证泄露到第三方域名
• 安全分析器：示例中还搭配了LLMSecurityAnalyzer（见 07_mcp_integration.py），对 Agent 的每个动作做风险研判
• 超时兜底：MCP 工具执行默认 300 秒超时（tool.py 中的MCP_TOOL_TIMEOUT_SECONDS），避免外部服务卡死整个会话

🧭 总结：MCP 集成的最短路径

1. 本地工具：MCPServer(command=..., args=[...])，stdio 传输，零额外依赖
2. 远程服务：MCPServer(url=..., transport=..., auth=...)，按鉴权类型选择api_key/bearer/basic/header/oauth2
3. 工具太多：用filter_tools_regex收窄暴露面
4. 上线前：通过 Agent Server 的/api/mcp/test端点做一次隔离校验
5. 安全：密钥自动脱敏、重定向防泄露、执行超时兜底

从声明式配置到自动工具注入，OpenHands Software Agent SDK 让 MCP 集成从"写胶水代码"变成了"填三行配置"。你的 Agent 由此不再受限于内置工具，而是可以直接站在整个 MCP 生态的肩膀上。