自建 MCP 服务并接入 Strands 代理
教程围绕 MCP Inspector 与 Strands Agents,讲解自建 MCP 服务及代理工具接入。配套 AWS 示例仓库提供练习骨架,运行需要 Python、uv 和可访问 Amazon Bedrock 的凭证。
AI 深度解读
把一个 Python 函数接到 AI Agent 上,为什么还要单独启动服务器、引入 MCP?作者用掷骰子演示了一条完整链路:把工具搬出 Agent 进程,先独立验证,再让 Strands Agents 发现和调用它。模型负责决定何时掷骰,服务器负责产生结果。
这篇教程的价值不在功能复杂,而在于把工具发现、参数校验、并发调用和日志核对拆开了。读完可以弄清 MCP 在 Agent 系统里负责哪一段,以及出了问题该从哪里查。
MCP 搬走了函数,没有搬走 Agent 的决策循环
原先,模型读取工具说明,决定调用 roll_dice,Strands 执行本地函数,再把结果交回模型。接入 MCP 后,函数在另一个程序里执行,模型的决策循环保持原样。
这里有三个角色:宿主是 AI 应用,本例是 Strands Agent;客户端负责连接服务器,宿主为每个服务器创建一个客户端并保持专用连接;服务器提供工具、资源和可复用提示词。
客户端通过 tools/list 获取工具清单,通过 tools/call 请求执行工具。消息采用 JSON-RPC 2.0:请求带 id、method 和 params,响应以相同 id 返回 result 或 error;通知没有 id,也不等待回复。
传输方式有两种。stdio 由客户端启动服务器子进程,通过标准输入输出通信,不开网络端口,适合单个客户端使用。Streamable HTTP 则让服务器独立运行,在一个端点接收 HTTP POST,允许多个客户端连接。跨机器共享时,需要处理 MCP 规范要求的授权。
作者选择后者,但监听地址仍是 127.0.0.1:8002,仅本机可访问。使用 HTTP 传输,不等于已经把工具发布成公共服务。
先证明服务器能工作,再让模型加入
运行示例需要 Python、uv、终端,以及能够访问 Amazon Bedrock 的 AWS 凭证。项目是 aws-samples/sample-once-upon-agentic-ai,主分支保留了带 # TODO 的代码骨架。
初始化依次使用 git clone、cd ~/sample-once-upon-agentic-ai、uv sync,再执行 export AWS_PROFILE=YOUR_AWS_PROFILE AWS_REGION=YOUR_AWS_REGION。AWS 凭证可通过 aws configure、环境变量、boto3 session 或 aws login 配置,Strands 会读取这些凭证。
服务器的核心代码解决的是:如何把原有函数暴露成 MCP 工具。
import random
import logging
from mcp.server import FastMCP
logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
mcp = FastMCP(port=8002)
@mcp.tool()
def roll_dice(faces: int = 6) -> int:
"""Roll one die with a given number of faces and return the result.
...
"""
if faces < 1:
raise ValueError("Dice must have at least 1 face")
result = random.randint(1, faces)
logging.info(f"... DICE ROLL: d{faces} = {result}")
return result
if __name__ == "__main__":
mcp.run(transport="streamable-http")
重点看 @mcp.tool() 和 if faces < 1。前者把文档字符串、类型标注转换为工具说明和输入 schema;后者才真正挡住非法面数。FastMCP 来自官方 MCP Python SDK,服务器里没有模型。
进入 ~/sample-once-upon-agentic-ai/4_mcp_integration,用 uv run python dice_roll_mcp_server.py 启动后,先别运行 Agent。作者用 MCP Inspector 独立检查服务器,避免工具错误和模型决策混在一起。
Inspector 需要 Node.js,可先用 node --version 检查。npx @modelcontextprotocol/inspector 会打开网页界面,选择 Streamable HTTP,填入 http://127.0.0.1:8002/mcp。
命令行模式更方便观察原始返回。下面两次调用分别验证正常路径和参数边界:
npx @modelcontextprotocol/inspector --cli http://127.0.0.1:8002/mcp --transport http --method tools/call --tool-name roll_dice --tool-arg faces=20
npx @modelcontextprotocol/inspector --cli http://127.0.0.1:8002/mcp --transport http --method tools/call --tool-name roll_dice --tool-arg faces=0
注意第二行的 faces=0。作者这次运行中,合法调用返回 19,同时出现在文本 content 和 structuredContent.result 中;非法调用返回 isError: true,Inspector 退出码为 5,服务器没有崩溃。
在这之前,把命令的 --method 设为 initialize,可以看到服务信息:name 为 FastMCP、version 为 1.30.0、protocolVersion 为 2025-11-25,工具能力中 listChanged 为 false。这些是该次示例返回的版本信息,不应直接当成所有环境的固定值。
再用 --method tools/list 检查定义:faces 是 integer,默认值为 6,输出 schema 中的 result 也是整数。但输入 schema 没有 minimum。
所以,faces=0 能通过 schema 检查,随后被函数拒绝。文档里的「至少 1 面」供模型理解,函数里的条件负责执行约束,两者承担不同责任。
模型拿到的是工具说明,结果来自服务器
Agent 端通过 MCPClient(url="http://localhost:8002/mcp") 创建客户端,再把它放进 Agent(..., tools=[mcp_dice_client])。客户端文件 gamemaster_mcp_client.py 不需要包含掷骰实现。
启动时,MCPClient 获取工具列表,把名称、描述和输入 schema 注册到 Agent。模型选择 roll_dice 后,Strands 才把调用转发给服务器。
这条自动接入路径针对 tools。服务器的 prompts 和 resources 仍由应用代码通过 list_prompts_sync()、get_prompt_sync()、list_resources_sync()、read_resource_sync() 获取,何时使用由开发者决定。

运行客户端前,同样设置 AWS_PROFILE、AWS_REGION,再用 aws sts get-caller-identity 检查身份,最后执行 uv run python gamemaster_mcp_client.py。凭证缺失或过期,会在模型调用阶段出现 NoCredentialsError 或令牌过期错误,与骰子服务器是否正常是两回事。
作者让模型按 4d6 drop lowest 生成力量、智慧、魅力和智力:每项掷四次六面骰,去掉最低值,共需 16 次工具调用。
将日志级别改成 DEBUG 后,客户端显示连接建立、会话初始化、收到 1 个工具,随后模型以 stop_reason=<tool_use> 请求调用。根日志还会输出 AWS SDK 请求和响应,因此作者建议搜索 mcp 和 stop_reason。
服务器则记录 ListToolsRequest、CallToolRequest 和每次 DICE ROLL。FastMCP 在进入函数前使用 Pydantic 按输入 schema 校验参数。第一项属性的结果是 3、6、4、2,丢掉 2 后得到 13。
作者核对了服务器的 16 次记录与模型随后收到的 16 个结果,数值一致;第 7、8 次结果的顺序发生交换,因为 Strands 会并发执行同一轮工具调用。
模型负责发起调用和解释结果,掷骰发生在服务器。 若回复与执行日志冲突,这个示例应以服务器记录为核对依据。
我的判断
我认同作者把 Inspector 放在 Agent 前面的顺序。先确定服务器返回什么,再检查模型如何使用它,排错范围会清楚很多。文档描述边界、函数执行边界,也是一条可以直接采用的工程习惯。
但作者展示的是成功跑通和日志核对,没有给出与本地工具调用的性能、稳定性或开发成本对照。不能据此判断 MCP 比直接注册函数更快、更可靠。
对于一个只服务单个 Python Agent 的骰子函数,本地工具更省事。MCP 的收益在于独立运行和统一接入;代价是多出进程、连接和部署管理。是否需要它,要看工具有没有跨应用复用的需求。
另外,示例只绑定本机地址,没有展开跨机器授权、超时和重试策略。它足以说明调用链,却还不是共享工具服务的完整生产方案。日志也只能证明这次工具执行了什么,不能代替对模型最终计算和文字表述的检查。
能拿来做什么
- 给日常 AI 编程工具接入自建 MCP 服务时,先用 Inspector 检查
initialize、tools/list和合法、非法参数调用,确认服务行为后再接模型。 - 如果准备让多个 AI 应用复用同一项能力,可以参考这个例子把执行逻辑独立出来;单个 Agent 内部使用的小函数,先保留本地工具即可。
- 定义工具时,同时检查描述、schema 和函数校验。尤其要确认范围限制有没有真正进入 schema,不能只看说明文字写得是否完整。
- 排查多次工具调用时,把客户端结果与服务器执行记录对应起来,不要按日志相邻顺序硬配;可以追加敏捷、体质两项属性,检查是否新增
8条掷骰记录。