English mirror

This English page is generated from the current Chinese documentation so every route, anchor, code sample, and language switch stays available on agently.tech. Human-edited English copy can replace this generated body page by page.

Read the Chinese source page

MCP

MCP 把外部工具服务暴露给 AI 应用。Agently 通过 MCPActionExecutor 把 MCP tool 接入 Action Runtime，所以模型会把 MCP tool 和本地 @agent.action_func 看成同一组可用能力。

如果工具已经由 MCP server 提供，不需要再把它包装成本地函数。

先分清 Server、Client 和 Host

MCP 接入企业系统时，最容易误判的是：写完 Server 不等于治理完成。

角色	负责什么
MCP Server	暴露工具、资源或 prompt，定义 schema，执行真实能力
MCP Client	管连接、握手、发现和调用转发
MCP Host	决定什么时候让模型看到哪个能力、如何注入身份、怎么脱敏、如何审计

Agently 的 use_mcp(...) 帮你把 MCP tools 接进 Action Runtime；业务应用仍要掌握 Host 责任。尤其是一个后端服务多个最终用户时，不能把桌面客户端式的 Host 假设直接搬进企业应用。

企业 Host 至少要处理：

• 当前 end-user 的身份和 token 如何透传到 MCP Server；
• 不同角色或任务阶段能看到哪些 MCP tools；
• 返回结果进入模型上下文前如何脱敏、聚合或裁剪；
• Host 为什么暴露、选择和调用某个工具，如何留下审计记录。

这些不是模型该即兴决定的内容，也不是 MCP Server 能单独替应用完成的业务编排。

先接一个 HTTP MCP endpoint

import asyncio
from agently import Agently

agent = Agently.create_agent()


async def main():
    await agent.use_mcp(
        "https://example.com/mcp",
        headers={"Authorization": "Bearer <token>"},
    )

    result = agent.input("用可用工具回答这个问题。").get_result()
    print(await result.async_get_text())


asyncio.run(main())

use_mcp(...) 是 async，因为它需要连接服务、列出 tools 并注册到 action surface。

HTTP、stdio 和 legacy SSE

服务集成优先使用 URL / Streamable HTTP MCP endpoint。本地开发、桌面客户端或单用户本地 server 可以用 stdio command config。SSE endpoint 只作为 legacy 兼容路径。

stdio 示例：

await agent.use_mcp({
    "mcpServers": {
        "filesystem": {
            "command": "npx",
            "args": [
                "-y",
                "@modelcontextprotocol/server-filesystem",
                "./workspace",
            ],
        }
    }
})

和本地 Action 混用

@agent.action_func
async def lookup_internal(id: str):
    """在内部数据库查记录。"""
    ...


await agent.use_mcp("https://example-mcp/server")
agent.use_actions([lookup_internal])

result = agent.input(question).get_result()
answer = await result.async_get_text()

MCP tools 和本地 actions 没有固定优先级。模型根据名称、描述和 prompt 上下文选择。

看实际调用了什么

turn = agent.input("使用 MCP server 回答这个问题。")
records = agent.get_action_result(prompt=turn.prompt)

for record in records:
    print(record)

action 记录写入 extra.action_logs。旧 tools 入口下的兼容字段是 extra.tool_logs。

密钥怎么传

优先使用 header 和环境变量：

await agent.use_mcp(
    "https://example.com/mcp",
    headers={"Authorization": f"Bearer {token}"},
)

URL query 参数可能进入日志。除非服务只能这样鉴权，否则不要把密钥拼在 URL 里。

什么时候不用 MCP

• 工具只是应用里的一个本地函数，直接用 @agent.action_func 更简单。
• 工具调用频率高、延迟敏感，hosted MCP 服务成为瓶颈。
• 需要本地托管 sandbox、browser、SQLite 生命周期，可以先看 Execution Environment。
• 还没有明确 Host 侧身份、可见工具裁剪、脱敏和审计策略。先把治理边界设计清楚，再接生产 MCP Server。

常见误用

• 忘记 await agent.use_mcp(...)。
• 把密钥放进 URL query。
• 把远程 MCP 当本地函数一样频繁调用，忽略网络延迟和限速。
• 手工把 MCP tool 描述写进 prompt，而不是让 action runtime 注入真实工具目录。
• 不看 action logs，无法确认模型到底调用了哪个 MCP tool。
• 把 MCP 当成权限和脱敏方案。MCP 标准化能力供应，企业治理仍要由 Host / Actions / ExecutionEnvironment / Observability 承担。

下一步

• Action Runtime：Action Runtime
• 托管资源生命周期：Execution Environment
• 工具治理与 Host 责任：工具治理与 MCP Host Playbook
• 兼容工具入口：工具兼容