使用 Serverless Framework 将 JavaScript MCP Server 部署到 AWS Bedrock AgentCore Runtime-港品优选

使用 Serverless Framework 将 JavaScript MCP Server 部署到 AWS Bedrock AgentCore Runtime

【免费下载链接】serverless⚡ Serverless Framework – Effortlessly build apps that auto-scale, incur zero costs when idle, and require minimal maintenance using AWS Lambda and other managed cloud services.项目地址: https://gitcode.com/GitHub_Trending/se/serverless

本指南以仓库内 mcp-server 示例为核心，完整讲解如何用一个最小可运行的 JavaScript 服务实现 Model Context Protocol（MCP），并通过 Serverless Framework 的ai配置将其实例化为 AgentCore Runtime 智能体，供 Cursor、Claude Desktop、Amazon Q CLI 等任意 MCP 客户端以 Streamable HTTP 远程消费。读完本文，你将掌握无状态 MCP Server 的服务端写法、serverless.yml中protocol: MCP的声明方式，以及用 AgentCore Runtime SDK 做端到端验证的完整闭环。

示例概览：一个可部署到 AgentCore Runtime 的 MCP Server

示例位于 packages/serverless/lib/plugins/aws/bedrock-agentcore/examples/javascript/mcp-server，是一个部署在 AWS Bedrock AgentCore Runtime 上的 JavaScript MCP Server。它通过 Model Context Protocol 暴露简单工具，任何实现了 MCP 客户端协议的生态（Cursor、Claude Desktop、Amazon Q CLI 等）都可以消费这些工具。

示例由 6 个文件构成，除 README 外，核心文件与职责如下：

文件	作用
index.js	MCP Server 实现（Express +`@modelcontextprotocol/sdk`，Streamable HTTP 传输）
package.json	依赖声明与`start`启动脚本
serverless.yml	Serverless Framework 配置，声明 AgentCore Runtime
test-invoke.js	基于 AWS SDK 的端到端调用验证脚本
package-lock.json	依赖锁文件

从仓库目录结构看，examples 下还提供了 LangGraph、Strands 等其他 JavaScript/Python 智能体示例，而本示例的定位最纯粹：只做 MCP 协议端点，不做业务 Agent 编排，适合作为接入 AgentCore MCP 协议的第一个落地实验。

示例暴露的三个工具

MCP Server 通过tools/list向客户端声明可用工具。本示例注册了三个工具：

工具	描述
`add`	将两个数字相加
`multiply`	将两个数字相乘
`get_current_time`	获取当前日期与时间（支持可选时区）

在 index.js 中，工具借助@modelcontextprotocol/sdk的server.registerTool注册，并用zod描述输入参数，从而自动生成符合 MCP 规范的inputSchema：

add与multiply：入参a、b均为z.number()，执行结果通过content: [{ type: 'text', text: ... }]返回；
get_current_time：入参timezone为可选的z.string()，代码注释中给出了"America/New_York"、"Europe/London"、"UTC"等典型取值；未传时默认UTC，最终调用Date.prototype.toLocaleString格式化输出。

这正好体现了 MCP 工具声明的核心范式：参数 Schema + 工具名 + 工具描述 + 异步执行函数，SDK 负责把这三者编译成标准 JSON-RPC 的tools/call处理流程。

前置条件

运行与部署本示例需要满足：

Node.js 24.x（package.json 中engines.node显式声明为24.x）；
已配置凭证的 AWS 账号（示例使用provider: aws，需要具备创建 Bedrock AgentCore 资源的权限）；
已全局安装 Serverless Framework：npm i -g serverless。

需要留意的是，AWS Bedrock AgentCore 只在部分区域开放，部署前应确认目标区域可用（详见插件 README 的 "Supported AWS Regions" 说明）。

服务端实现：无状态的 Streamable HTTP MCP 端点

index.js 的核心设计思想是无状态（stateless）：Server 通过 Express 在8000端口暴露POST /mcp端点，该端点即 AgentCore Runtime 对 MCP 协议 runtime 的预期入口。

具体实现分三层：

1. MCP Server 工厂

createMcpServer()每次被调用都会创建一个全新实例：

const server = new McpServer({ name: 'mcp-server', version: '1.0.0', })

工具注册、Schema 校验都在这个工厂函数内完成，因此每个 HTTP 请求拿到的是彼此隔离、互不共享状态的 server 实例——这正是云上无状态容器所期望的行为。

2. Streamable HTTP 传输接入

app.post('/mcp', async (req, res) => { const server = createMcpServer() const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, // 无状态——不维护持久会话 enableJsonResponse: true, }) await server.connect(transport) res.on('close', () => { transport.close() server.close() }) await transport.handleRequest(req, res, req.body) })

关键点：sessionIdGenerator: undefined显式关闭会话复用，确保每个请求独立处理 JSON-RPC 消息，并在响应关闭（close）时清理 transport 与 server 资源。这也是与 MCP 官方StreamableHTTPServerTransport面向"每请求一实例"部署模型的典型配合方式。

3. 协议边界处理与错误兜底

GET /mcp按 MCP 规范返回405 Method Not Allowed，错误体为标准 JSON-RPC 格式（code-32000）；
请求处理抛出异常时，若响应头尚未发出，则以 JSON-RPC 错误码-32603（Internal server error）返回500，保证协议格式始终自洽；
服务监听0.0.0.0:8000，容器内打印MCP server running on http://0.0.0.0:8000/mcp便于排查。

从 runtime.js 编译器的注释可印证：AgentCore Runtime 的ProtocolConfiguration只是字符串枚举（HTTP、MCP、A2A），运行时内部按协议类型路由流量，因此 HTTP 层 + JSON-RPC 的 MCP 载荷结构是接通 AgentCore 的关键前提。

配置解析：serverless.yml 如何声明一个 MCP 协议 Agent

示例的 serverless.yml 极其精简：

service: mcp-server provider: name: aws ai: agents: assistant: protocol: MCP

它依赖的是 Bedrock AgentCore 插件暴露的顶层ai属性（插件文档见 bedrock-agentcore/README.md）。ai.agents用于定义 Runtime Agent，示例在此设置了关键项：

service: mcp-server：服务名，作为资源命名的组成部分；
provider.name: aws：AWS 提供商；
ai.agents.assistant.protocol: MCP：告诉 AgentCore 把发往该 Runtime 的流量按 MCP 协议路由。

在插件 README 的 Runtime Agent 属性表中，protocol的合法取值为http、mcp或a2a。查看 compilers/runtime.js 的buildProtocolConfiguration实现可以看到：无论是字符串简写（protocol: 'MCP'）还是对象形式（protocol: { type: 'MCP' }），编译器最终都会将其规范化为大写枚举，并写入生成的AWS::BedrockAgentCore::Runtime资源的ProtocolConfiguration属性。

此外，示例没有提供 Dockerfile、也没有声明handler/runtime，说明本示例采用"code deployment"路径：编译器会根据是否存在entryPoint判定是否走代码打包上传（runtime.js 第 255-270 行），配合插件在部署时自动构建容器并注入环境。若你对更复杂的 Agent 声明（内存、网关、工具、鉴权、VPC 网络等）感兴趣，可继续阅读插件 README。

部署与本地开发

部署到 AWS

在mcp-server目录执行：

npm install sls deploy

npm install安装express、@modelcontextprotocol/sdk、zod等依赖（详见 package.json）；
sls deploy生成 CloudFormation 模板并创建 AgentCore Runtime 资源。

按插件 README 说明，部署后插件会自动创建形如{Name}RuntimeArn、{Name}RuntimeId的 CloudFormation 输出。可用sls info查询已部署资源的 Runtime ARN——这也是下文验证脚本所需的输入。

本地开发

npm install sls dev

sls dev提供带热重载（hot reload）的本地开发体验（详见插件 README 的命令列表），便于在推送云端前快速迭代工具逻辑。

日常运维可配合sls logs --agent assistant拉取 Agent 日志、sls remove清理资源。

将 MCP 客户端接入已部署的 Runtime

部署完成后，该 Runtime 可被任何支持通过 Streamable HTTP 接入远程 MCP Server的客户端消费。连接方式与鉴权配置属于 AgentCore 的调用侧细节：示例 README 明确指出，调用细节与认证设置请参考 AgentCore 官方 MCP 运行时文档（仓库内该 README 首尾均有对应外链指引）。

实操上的参考路径是：先用下文的管理端 SDK 完成initialize等握手验证，确认端点与鉴权就绪后，再把 Runtime URL 配置到 Cursor、Claude Desktop 或 Amazon Q CLI 的 MCP Server 配置中。

端到端验证：用 AgentCore Runtime SDK 调用 MCP 工具

示例自带的 test-invoke.js 是一个不依赖第三方 MCP 客户端的验证脚本，它直接用 AWS SDK 的BedrockAgentCoreClient向已部署 Runtime 发送 JSON-RPC 消息，非常适合在连接 GUI 客户端之前确认服务端一切正常。

使用方式

npm install @aws-sdk/client-bedrock-agentcore RUNTIME_ARN=arn:aws:bedrock-agentcore:... node test-invoke.js

RUNTIME_ARN必填（可用sls info获取）；缺失时脚本会打印用法并退出；
AWS_REGION可选，默认us-east-1；
每次InvokeAgentRuntimeCommand请求都会携带qualifier: 'DEFAULT'，首响应返回的runtimeSessionId会被缓存并用于后续消息（test-invoke.js 第 36-50 行）。

脚本执行的完整 MCP 会话

脚本按 MCP 标准握手顺序逐步验证，每一步都打印对应结果：

initialize（JSON-RPC id=1）：声明protocolVersion: '2025-11-25'与客户端信息，校验服务端返回的serverInfo与协议版本；
notifications/initialized：携带已缓存的runtimeSessionId发送初始化完成通知；
tools/list（id=2）：枚举服务端工具列表，输出add、multiply、get_current_time及其描述；
tools/call：依次真实调用四个用例——add(5, 3)、multiply(7, 6)、get_current_time('UTC')、get_current_time('America/New_York')，并打印每个调用的文本结果（test-invoke.js 第 106-114 行）。

此外，脚本还处理了响应可能是字符串、字节流或 ReadableStream 的多种形态（streamToString辅助函数），保证在accept: 'application/json, text/event-stream'的流式返回下也能正确解析。

该脚本与 index.js 一起构成"服务端实现 + 协议级验证"的完整闭环：前者证明 HTTP 端点与工具注册逻辑正确，后者证明 Runtime 的路由、会话与 JSON-RPC 转发在 AWS 侧链路畅通。

小结：从示例到自有 MCP Server

这个最小示例演示了把 MCP 工具送上云的一条极简路径：在 Express 里用@modelcontextprotocol/sdk实现无状态POST /mcp端点，再通过 Serverless Framework 的ai.agents.<name>.protocol: MCP把它注册为 AgentCore Runtime。接下来扩展自己的服务时，只需在createMcpServer中继续调用registerTool添加业务工具，并把 serverless.yml 补充上环境变量、网络模式或生命周期等配置（参考插件 README 的属性表），即可让现有客户端立刻消费新能力。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析