基础篇
进阶篇
高频篇
精选篇
手写篇
面经篇
AI 篇
原理篇
每日一题
小程序题库
  • 知识卡片碎片时间过考点
  • 场景篇按分类整理的大前端场景考点
  • 历年面经按年份追踪真实考点
  • 算法题库NEW在线编码即时判题
  • 专项自测100 题快速查漏
  • 前端基础
    • HTTP从报文一路讲到 HTTPS
    • 浏览器渲染、事件循环、进程
    • 计算机基础Linux、网络、操作系统
  • 进阶专项
    • 设计模式23 种模式怎么用
    • 前端系统进阶学习大型项目工程化
    • 前端综合文章长期沉淀的实践文
  • 工程与工具
    • Node学习指南从环境搭建到服务端
    • NPM工作流script、依赖与发布
    • Docker容器化部署上手
    • Canvas图形与动画实战
  • 路线与导图
    • 思维导图知识点全景图
    • 学习路线按图索骥不跑偏
  • 动态
    • 公众号动态公众号历史文章
    • 博客动态站长的技术博客
    • 开发者导航常用工具与文档站
    • AI 热点每日 AI 资讯与动向
AI 工作台
旧版
AIHT
内容
精选全部 AI 动态热点榜AI 日报收藏
分类
模型行业编程产品技术观点开源
更多
Agent 接入
返回首页开发者导航
AIHT
精选 / 资讯详情
8.0
热点
AI SCORE
技术实践2026-11-17 16:35

自建 MCP 服务并接入 Strands 代理

dev.to · AI#MCP#Agent#AWS
Editor brief · 编辑速览

教程围绕 MCP Inspector 与 Strands Agents,讲解自建 MCP 服务及代理工具接入。配套 AWS 示例仓库提供练习骨架,运行需要 Python、uv 和可访问 Amazon Bedrock 的凭证。

文章思维导图
Knowledge map
拖拽缩放
AI deep read

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() 获取,何时使用由开发者决定。

Strands 通过 MCP 客户端调用服务器工具

运行客户端前,同样设置 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 条掷骰记录。
Original source

本文由 AI 通读原文后重新编写,观点部分为站内判断,细节以原文为准,来源 dev.to · AI,原文版权归原作者所有。

阅读原文
上一篇
多智能体审查找出命令沙箱绕过路径
下一篇
浏览器代理用截图还是无障碍树更省

资讯速览

dev.to · AI · 2026-11-17 16:35

AI 评分 8.0 / 10

相关标签

#MCP#Agent#AWS

继续阅读

  • 宽松类型校验掩盖了模型输出错误
  • 多智能体审查找出命令沙箱绕过路径
  • 浏览器代理用截图还是无障碍树更省
  • Agent 上线要补齐哪些工程能力
  • 本地 Agent 选模型,先看吞吐与并发