400 个私有 API 如何接入 Agent 工具层

把 400 个内部 API 交给 AI Agent，难点不在调用接口，而在于：接口不能出公网，模型不能决定租户身份，工具列表也不能挤满上下文。MoEngage 的做法是让产品团队继续维护 REST API，由平台团队统一处理 MCP、权限和私网连接。

这篇案例值得看的，是一套已经运行的分工方式：新增工具变成 OpenAPI 标注和 CI 流水线操作。不过，「节省约六个月工程投入」是团队估算，不能直接当作所有公司的收益预期。

为什么不让每个团队各写一个 MCP Server

MoEngage 服务超过 1,350 个消费品牌，覆盖 push、email、in-app、SMS、WhatsApp 和 RCS。它的约 400 个内部 REST API 来自 25 个工程团队，分布在七个 AWS Region 的私有 VPC 中，并按区域隔离以满足数据驻留承诺。

如果各团队分别接入 Model Context Protocol（MCP），就要维护超过 20 个 MCP Server，包括部署、监控、补丁和协议兼容。一个需要读取营销活动、检查人群、查看投递统计的 Agent，还得连接多个服务。

他们因此划了一条边界：产品团队负责 API 和描述完整的 OpenAPI 规范；AI Platform 团队负责协议、策略和连接。

自建一个中央 MCP Server 也能减少部署数量，但工具生成、策略格式、改名别名表、熔断器仍要自己维护。AgentCore Gateway 的价值，是承接这些公共设施。它是 Amazon Bedrock AgentCore 提供的托管 MCP Server，注册 OpenAPI target 后，可以生成工具并转发调用。

工具名称遵循 Target___operationId，例如 CampaignsAPI___searchCampaigns。规范更新后，经发布流程同步，工具也随之变化。

这套方案首先解决的是团队分工，再用托管服务降低执行这套分工的成本。

工具能不能看见，必须由服务端决定

原文按每个工具 JSON Schema 约 50 tokens 估算，全量 tools/list 超过 20,000 tokens。这个预算在 Agent 开始处理任务前就花掉了。

在 ADK 或 MCP SDK 中使用 tool_filter，只能在客户端过滤已经收到的目录，既没有省下传输，也不能构成授权边界。一个只允许检查活动的机器人，不应该先收到发布活动的工具，再靠提示词约束自己。

MoEngage 为每个 Agent 分配独立 IAM role，由 Cedar 策略决定它能发现和调用哪些工具。网关通过部分求值，在序列化 tools/list 响应前完成筛选。

下面的策略让活动 QA 机器人获得活动读取权限，并明确禁止写操作：

permit(
    principal == Agent::"campaign-qa-bot-v1",
    action == Action::"tools/call",
    resource in ToolGroup::"campaigns-read"
);

forbid(
    principal == Agent::"campaign-qa-bot-v1",
    action == Action::"tools/call",
    resource in ToolGroup::"write-actions"
);

要看的是第二段 forbid：写操作的限制由服务端执行，相应工具也不会出现在该机器人的目录里。

授权后，工具子集仍可能很大。客户端库因此只向模型暴露一个元工具 search_tools，模型先描述任务，再把搜索到的候选工具加入本轮可调用集合。

网关提供的语义搜索能力名为 x_amz_bedrock_agentcore_search。它还降低了对工具名的依赖：get_segment_user_count 改成 get_segment_size 后，按人群用户数量搜索仍可能找到对应工具。

这里有两道独立关卡：权限决定工具能否使用，搜索决定当前任务需要哪些工具。搜索不能代替授权。

身份不进参数，API 接入才适合自动化

调用链从运行在 Amazon EC2 或容器中的 Agent 服务开始。客户端可以使用官方 MCP SDK、LangChain、Google ADK，或者 MoEngage 自己的 agent runner。

请求使用服务已有 IAM role 的凭证进行 SigV4 签名，通过 HTTPS、带 private DNS 的 VPC interface endpoint 到达网关。网关检查 Cedar 策略，再经 Amazon VPC Lattice 上的 managed egress 访问内部 API。这条内部调用链没有公网跳转，新增 API 添加 target 即可复用连接设施。

身份另走一条受控路径。租户、用户、角色和数据库上下文由客户端库从 Identity 对象转换成 X-MOE-* 请求头，不作为模型可填写的工具参数。

原文还给出两个容易踩坑的细节：SigV4 占用了 Authorization，需要继续传递的 bearer token 必须放到专用 MoEngage 前缀请求头；请求头传播数量也有限制，不能无限追加。

列举和搜索工具不携带租户身份，只有 tools/call 携带。因此，带业务身份的请求对应实际数据访问。面向 Claude 等客户端、承载人工登录会话的独立公共 MCP Server 则使用 AgentCore runtime 和 OIDC JWTs，这是另一套入口。

产品团队接入工具时，在现有 OpenAPI 中添加以下标注：

paths:
  /campaigns:
    get:
      operationId: listCampaigns
      description: |
        Returns a paginated list of campaigns. Supports filtering by
        status, channel, date range, and tags.
      x-moe-mcp:
        expose:
          external: false
          internal: true
        tool_description: |
          Find campaigns by status or channel. Returns campaign ID, name,
          status, and channel. Use the returned campaign_id with
          get_campaign for full details, or send_campaign to launch it.
        param_overrides:
          status:
            description: |
              Filter by campaign status. Use 'active' for running
              campaigns, 'scheduled' for upcoming. Omit for all.

重点是 x-moe-mcp：没有这个块，端点就不会成为工具。internal 和 external 分别控制两个入口，缓存预热、迁移触发等接口可以继续保持不暴露。

另一个关键字段是 tool_description。开发者文档告诉人接口返回什么，工具描述需要告诉模型什么时候用、传什么、返回结果接下来怎么用。团队发现，直接复用 API 描述会让模型围绕实现细节选工具，因此另设 tool_description 和 param_overrides。

CI 负责校验标注、注册 target、应用 Cedar 策略。协议和策略实现仍归平台团队维护，产品团队通过规范变更接入。客户端库同时提供框架插件模式和完整 agent runner 模式。

我的判断

这套设计最值得借鉴的是身份隔离。租户和权限上下文不应成为模型可自由生成的业务参数。 即使不用 AgentCore，也应该保留这条边界；下游 API 是否正确验证这些身份，仍需单独保证。

案例已经在七个 AWS Region 运行，向 10 个内部 Agent 提供约 400 个已注册 API operation。原文称系统在生产环境运行了三个月，覆盖活动 QA、投递健康检查和自然语言人群构建。团队估计节省约六个月工程投入，API 接入从数天缩短到数小时。

但文章没有提供自建方案的对照测试，也没给费用、延迟、搜索命中率和错误调用率。「节省六个月」属于经验估算，不能据此证明托管方案在所有规模下都更划算。

它的适用前提也很明确：已有 AWS 身份体系、私网基础设施，以及维护平台能力的团队。工具较少的小团队，自建集中式适配层可能更容易控制；工具和组织规模接近案例时，托管方案的收益才更值得计算。各 Region 的功能可用性还存在差异，不能只看这个案例就假定部署条件一致。

语义搜索也有边界。改名后能被发现，不代表参数、返回值或业务语义变化后仍兼容。原文没有交代候选排序和误选的评估方式，对写操作尤其不能省掉验证。

能拿来做什么

• 给现有 Node 服务接入 Agent 时，先整理 API 的可暴露范围，把租户、用户和角色从工具参数中移出，由可信调用服务注入，并检查下游如何验证这些身份。
• 为 OpenAPI 单独补充模型可读的工具说明，写清使用时机、参数含义和结果用途；先从只读查询开始，避免默认暴露全部路由。
• 工具数量增多后，采用服务端权限筛选与按任务搜索，检查未授权工具是否确实无法发现和调用，不要只验证前端或客户端是否隐藏了它们。
• 评估集中式 MCP 接入时，同时记录新增 API 的接入耗时、搜索命中情况、调用延迟和运行费用，用自己的数据判断是否需要托管网关。