把可复用的 MCP 工具接入 Amazon Quick：从 AgentCore Runtime 托管到生产集成

预计阅读时间：10 分钟

如果一个产品已经积累了查询、分析或自动化工具，就不应该为每个 AI 客户端重复编写一套连接器。将 MCP server 部署到 Amazon Bedrock AgentCore Runtime，再接入 Amazon Quick，可以把这些能力作为可复用工具提供给 Quick 中的聊天代理和工作流。

这种架构的关键不只是“把服务部署起来”，而是建立一条清晰的工具复用链路：MCP server 负责暴露能力，AgentCore Runtime 负责托管和运行，Amazon Quick 负责面向最终用户编排交互。

一条连接链路，解决多次集成

可以把整体关系理解为：

你的业务系统或数据源
          |
          v
      MCP server
          |
          v
AgentCore Runtime 托管与运行
          |
          v
 Amazon Quick 聊天代理 / 工作流

MCP server 是复用边界。它不需要知道每个客户端如何展示结果，只需要把工具、输入参数和返回结果定义清楚。Quick 可以调用这些已经存在的工具，客户也就能在 Quick 的聊天代理和工作流中使用你的产品，而不必为每个场景单独开发自定义连接器。

这还带来一个实际收益：工具逻辑集中维护。权限校验、参数验证、超时处理和业务规则可以在 MCP server 内统一实现，客户端只负责发现和调用。

开始前需要确认什么

部署前至少需要准备以下内容：

一个符合 MCP 约定的 server，以及可由它调用的业务 API、数据库或内部服务。
AWS 账号和相应区域中的 AgentCore Runtime、Amazon Quick 使用权限。
用于构建、部署和运行 MCP server 的本地环境或 CI/CD 环境。
AgentCore Runtime 执行角色，以及访问业务依赖所需的最小 IAM 权限。
MCP server 的稳定访问地址、认证方式和网络策略。
Quick 侧允许访问该 MCP server 的配置，以及需要暴露给用户的工具清单。

不要把本地开发地址直接交给 Quick。生产环境应使用稳定的运行时入口，并明确 TLS、身份认证、日志和超时策略。具体的 AgentCore Runtime 部署命令和 Quick 管理界面选项可能随 AWS 发布的工具版本变化，下面的配置示例应当作为项目模板，根据当前账号和区域的官方配置进行调整。

一个可改造的部署配置

下面是一个简化的 YAML 模板，展示部署时应明确的配置项。字段名称是示意性的，实际使用时请以当前 AgentCore Runtime 部署工具支持的 schema 为准：

# agentcore-runtime.yaml
runtime:
  name: product-tools-mcp
  region: us-east-1
  container:
    image: 123456789012.dkr.ecr.us-east-1.amazonaws.com/product-tools-mcp:2025-01
    port: 8080
    healthCheck:
      path: /health
      intervalSeconds: 30
  environment:
    PRODUCT_API_BASE_URL: https://api.example.com
    MCP_LOG_LEVEL: INFO
  executionRoleArn: arn:aws:iam::123456789012:role/ProductToolsMcpRuntimeRole
  network:
    mode: private
    securityGroupIds:
      - sg-0123456789abcdef0

部署前把账号、区域、镜像地址、角色 ARN 和业务 API 地址替换成真实值。镜像中的进程必须监听运行时提供的端口，并实现健康检查；否则服务即使完成部署，也可能无法被 Quick 稳定调用。

可以先用下面的命令验证镜像或运行时入口是否至少能够响应健康检查：

export MCP_ENDPOINT="https://your-runtime-endpoint.example.com"

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer ${MCP_ACCESS_TOKEN}" \
  "${MCP_ENDPOINT}/health"

如果服务采用 SigV4、OAuth 或其他身份机制，应把示例中的 Bearer token 替换成对应的认证方式。健康检查通过并不代表 MCP 调用一定成功，还需要验证工具发现、参数校验和实际业务权限。

接入 Quick 时关注工具契约

接入 Amazon Quick 时，建议只暴露已经稳定、边界清晰的工具。例如，与其暴露一个“执行任意 SQL”的工具，不如提供 find_customer_orders、get_inventory_status 这类带有明确参数和权限边界的工具。

每个工具至少应定义：

工具名称和用途，名称要能帮助代理选择正确能力。
必填参数、类型、枚举值和默认行为。
成功返回值的结构，以及无结果时的表达方式。
可预期的业务错误，例如无权限、资源不存在和请求超时。
是否会产生写入、发送消息或其他不可逆副作用。

可以用一组最小的请求流程做联调。下面的路径和请求体是 MCP 服务适配层的示意写法，实际字段应以你采用的 MCP SDK 和传输模式为准：

export MCP_ENDPOINT="https://your-runtime-endpoint.example.com"
export MCP_ACCESS_TOKEN="replace-me"

# 1. 发现工具
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer ${MCP_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  "${MCP_ENDPOINT}/mcp"

# 2. 调用一个只读工具
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer ${MCP_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"tools/call",
    "params":{
      "name":"find_customer_orders",
      "arguments":{"customer_id":"CUST-1001","limit":10}
    }
  }' \
  "${MCP_ENDPOINT}/mcp"

完成服务端联调后，再在 Quick 中配置 MCP server 的入口和认证信息，选择需要发布的工具，并通过一个聊天代理或工作流验证完整链路。测试问题应覆盖正常查询、空结果、参数错误、权限不足和后端超时，而不是只验证一次成功调用。

生产化时的边界

MCP server 成为多个客户端共用的能力层后，任何接口变化都可能影响多个代理和工作流。建议为工具输入和输出建立版本策略，避免直接删除或重命名已经被使用的工具。对新增字段优先保持向后兼容，并记录工具变更。

安全方面，执行角色应只拥有访问必要资源的权限。认证凭据不要硬编码到镜像或 YAML 文件中，应使用适合运行时的密钥管理方式。对于会修改数据的工具，增加幂等键、审批步骤或明确的二次确认，避免代理误调用造成不可逆操作。

运维方面，应记录请求 ID、工具名称、调用耗时、结果状态和错误类别，同时避免把客户数据和访问令牌写入普通日志。为每个工具设置合理超时和限流，防止 Quick 中的并发工作流放大下游压力。

落地检查清单

MCP server 可以在目标运行时独立启动，并通过健康检查。
Runtime 的执行角色只包含必要权限。
Quick 能发现预期工具，并能调用一个只读工具。
参数错误、空结果、权限错误和超时都有可理解的返回信息。
工具输入输出具备版本兼容策略。
日志、指标、告警和审计记录已经配置。
写入类工具具备幂等、审批或确认机制。
已完成 Quick 聊天代理和工作流中的真实场景测试。

采用这种方式的价值，在于把一次实现变成多个 AI 入口都能复用的产品能力。真正值得投入的地方不是复制更多连接器，而是把 MCP 工具的契约、权限和运维边界设计扎实，再让 AgentCore Runtime 和 Amazon Quick 承担托管与消费这两端的工作。