@aws/run-mcp-servers-with-aws-lambda 0.3.4 → 0.4.0

package/README.md

@@ -43,13 +43,14 @@ Each Lambda function invocation will:
 1. Return the server's response to the function caller
 1. Shut down the MCP server child process
 
-This library supports connecting to Lambda-based MCP servers in three ways:
+This library supports connecting to Lambda-based MCP servers in four ways:
 
 1. The [MCP Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http), using Amazon API Gateway. Typically authenticated using OAuth.
-2. A custom Streamable HTTP transport with support for SigV4, using a Lambda function URL. Authenticated with AWS IAM.
-3. A custom Lambda invocation transport, using the Lambda Invoke API directly. Authenticated with AWS IAM.
+1. The MCP Streamable HTTP transport, using Amazon Bedrock AgentCore Gateway (currently in Preview). Authenticated using OAuth.
+1. A custom Streamable HTTP transport with support for SigV4, using a Lambda function URL. Authenticated with AWS IAM.
+1. A custom Lambda invocation transport, using the Lambda Invoke API directly. Authenticated with AWS IAM.
 
-## Using API Gateway
+## Use API Gateway
 
 ```mermaid
 flowchart LR
@@ -206,7 +207,192 @@ See a full example as part of the sample chatbot [here](examples/chatbots/typesc
 
 </details>
 
-## Using a Lambda function URL
+## Use Bedrock AgentCore Gateway
+
+```mermaid
+flowchart LR
+    App["MCP Client"]
+    T1["MCP Server<br>(Lambda function)"]
+    T2["Bedrock AgentCore Gateway"]
+    T3["OAuth Server<br>(Cognito or similar)"]
+    App -->|"MCP Streamable<br>HTTP Transport"| T2
+    T2 -->|"Invoke"| T1
+    T2 -->|"Authorize"| T3
+```
+
+This solution is compatible with most MCP clients that support the streamable HTTP transport.
+MCP servers deployed with this architecture can typically be used with off-the-shelf
+MCP-compatible applications such as Cursor, Cline, Claude Desktop, etc.
+
+You can choose your desired OAuth server provider with Bedrock AgentCore Gateway,
+such as Amazon Cognito, Okta, or Auth0.
+
+Using Bedrock AgentCore Gateway in front of your stdio-based MCP server requires that
+you retrieve the MCP server's tool schema, and provide it in the
+[AgentCore Gateway Lambda target configuration](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-add-target-lambda.html#gateway-lambda-schema).
+AgentCore Gateway can then advertise the schema to HTTP clients and validate request inputs and outputs.
+
+To retrieve your stdio-based MCP server's tool schema:
+
+1. Start the MCP inspector: `npx @modelcontextprotocol/inspector`
+2. Open the inspector tool in your web browser using the localhost link shown.
+3. In the left-hand column, select STDIO transport type, and fill in your server's command and arguments. For example, command `uvx` and arguments `mcp-server-time`.
+4. Click Connect.
+5. In the main panel, select Tools and click "List Tools".
+6. In the bottom "History" panel, select the `tools/list` request.
+7. In the Response box, click the Copy clipboard icon in the upper-right corner of the box.
+8. Paste the JSON into a new file. It should begin with `{ tools:[...`
+9. Add a new key "arn" to your JSON file with the value of your Lambda function's ARN.
+
+Your Lambda function schema should now look something like this:
+
+```json
+{
+  "arn": "arn:aws:lambda:us-west-2:123456789012:function:MyFunction",
+  "tools": [
+    {
+      "name": "process_data",
+      "description": "Process input data",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "input": { "type": "string" }
+        },
+        "required": ["input"]
+      }
+    }
+  ]
+}
+```
+
+<details>
+
+<summary><b>Python server example</b></summary>
+
+```python
+import sys
+from mcp.client.stdio import StdioServerParameters
+from mcp_lambda import BedrockAgentCoreGatewayTargetHandler, StdioServerAdapterRequestHandler
+
+server_params = StdioServerParameters(
+    command=sys.executable,
+    args=[
+        "-m",
+        "my_mcp_server_python_module",
+        "--my-server-command-line-parameter",
+        "some_value",
+    ],
+)
+
+
+request_handler = StdioServerAdapterRequestHandler(server_params)
+event_handler = BedrockAgentCoreGatewayTargetHandler(request_handler)
+
+
+def handler(event, context):
+    return event_handler.handle(event, context)
+```
+
+</details>
+
+<details>
+
+<summary><b>Typescript server example</b></summary>
+
+```typescript
+import { Handler, Context } from "aws-lambda";
+import {
+  BedrockAgentCoreGatewayTargetHandler,
+  StdioServerAdapterRequestHandler,
+} from "@aws/run-mcp-servers-with-aws-lambda";
+
+const serverParams = {
+  command: "npx",
+  args: [
+    "--offline",
+    "my-mcp-server-typescript-module",
+    "--my-server-command-line-parameter",
+    "some_value",
+  ],
+};
+
+const requestHandler = new BedrockAgentCoreGatewayTargetHandler(
+  new StdioServerAdapterRequestHandler(serverParams)
+);
+
+export const handler: Handler = async (
+  event: event: Record<string, unknown>,
+  context: Context
+): Promise<event: Record<string, unknown>> => {
+  return requestHandler.handle(event, context);
+};
+```
+
+</details>
+
+<details>
+
+<summary><b>Python client example</b></summary>
+
+```python
+from mcp import ClientSession
+from mcp.client.streamable_http import streamablehttp_client
+
+# Create OAuth client provider here
+
+async with streamablehttp_client(
+    url="https://abc123.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp",
+    auth=oauth_client_provider,
+) as (
+    read_stream,
+    write_stream,
+    _,
+):
+    async with ClientSession(read_stream, write_stream) as session:
+        await session.initialize()
+        tool_result = await session.call_tool("echo", {"message": "hello"})
+```
+
+See a full example as part of the sample chatbot [here](examples/chatbots/python/server_clients/interactive_oauth.py).
+
+</details>
+
+<details>
+
+<summary><b>Typescript client example</b></summary>
+
+```typescript
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+
+const client = new Client(
+  {
+    name: "my-client",
+    version: "0.0.1",
+  },
+  {
+    capabilities: {
+      sampling: {},
+    },
+  }
+);
+
+// Create OAuth client provider here
+
+const transport = new StreamableHTTPClientTransport(
+  "https://abc123.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp",
+  {
+    authProvider: oauthProvider,
+  }
+);
+await client.connect(transport);
+```
+
+See a full example as part of the sample chatbot [here](examples/chatbots/typescript/src/server_clients/interactive_oauth.ts).
+
+</details>
+
+## Use a Lambda function URL
 
 ```mermaid
 flowchart LR
@@ -358,7 +544,7 @@ See a full example as part of the sample chatbot [here](examples/chatbots/typesc
 
 </details>
 
-## Using the Lambda Invoke API
+## Use the Lambda Invoke API
 
 ```mermaid
 flowchart LR
@@ -506,7 +692,7 @@ See a full example as part of the sample chatbot [here](examples/chatbots/typesc
   Other languages such as Kotlin are not supported.
 - This library only adapts stdio MCP servers for Lambda, not servers written for other protocols such as SSE.
 - This library does not maintain any MCP server state or sessions across Lambda function invocations.
-  Only stateless MCP servers are a good fit for using this adapter. For example, MCP servers
+  Only stateless MCP servers are a good fit for using this library. For example, MCP servers
   that invoke stateless tools like the [time MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/time)
   or make stateless web requests like the [fetch MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/fetch).
   Stateful MCP servers are not a good fit, because they will lose their state on every request.

package/dist/handlers/bedrockAgentCoreGatewayTargetHandler.d.ts

@@ -0,0 +1,17 @@
+import { Context } from "aws-lambda";
+import { RequestHandler } from "./requestHandler.js";
+/**
+ * Handler for Bedrock AgentCore Gateway Lambda targets
+ *
+ * This handler processes direct Lambda invocations from Bedrock AgentCore Gateway.
+ * Bedrock AgentCore Gateway passes tool arguments directly in the event and
+ * provides metadata through the Lambda context's client_context.custom properties.
+ */
+export declare class BedrockAgentCoreGatewayTargetHandler {
+    private requestHandler;
+    constructor(requestHandler: RequestHandler);
+    /**
+     * Handle Lambda invocation from Bedrock AgentCore Gateway
+     */
+    handleEvent(event: Record<string, unknown>, context: Context): Promise<unknown>;
+}

package/dist/handlers/bedrockAgentCoreGatewayTargetHandler.js

@@ -0,0 +1,39 @@
+import { isJSONRPCError, } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * Handler for Bedrock AgentCore Gateway Lambda targets
+ *
+ * This handler processes direct Lambda invocations from Bedrock AgentCore Gateway.
+ * Bedrock AgentCore Gateway passes tool arguments directly in the event and
+ * provides metadata through the Lambda context's client_context.custom properties.
+ */
+export class BedrockAgentCoreGatewayTargetHandler {
+    requestHandler;
+    constructor(requestHandler) {
+        this.requestHandler = requestHandler;
+    }
+    /**
+     * Handle Lambda invocation from Bedrock AgentCore Gateway
+     */
+    async handleEvent(event, context) {
+        // Extract tool metadata from context
+        const toolName = context.clientContext?.Custom?.["bedrockagentcoreToolName"];
+        if (!toolName) {
+            throw new Error("Missing bedrockagentcoreToolName in context");
+        }
+        // Create JSON-RPC request from gateway event
+        const jsonRpcRequest = {
+            jsonrpc: "2.0",
+            id: 1,
+            method: "tools/call",
+            params: {
+                name: toolName,
+                arguments: event,
+            },
+        };
+        const result = await this.requestHandler.handleRequest(jsonRpcRequest, context);
+        if (isJSONRPCError(result)) {
+            throw new Error(result.error.message);
+        }
+        return result.result;
+    }
+}

package/dist/handlers/handlers.test.js

@@ -1,5 +1,5 @@
 import { ErrorCode, } from "@modelcontextprotocol/sdk/types.js";
-import { APIGatewayProxyEventHandler, APIGatewayProxyEventV2Handler, LambdaFunctionURLEventHandler, } from "./index.js";
+import { APIGatewayProxyEventHandler, APIGatewayProxyEventV2Handler, LambdaFunctionURLEventHandler, BedrockAgentCoreGatewayTargetHandler, } from "./index.js";
 // Mock RequestHandler implementation for testing
 class MockRequestHandler {
     responses = new Map();
@@ -627,3 +627,45 @@ describe("MCP Streamable HTTP Handlers", () => {
         });
     });
 });
+describe("BedrockAgentCoreGatewayTargetHandler", () => {
+    let mockRequestHandler;
+    let handler;
+    let mockContext;
+    beforeEach(() => {
+        mockRequestHandler = new MockRequestHandler();
+        handler = new BedrockAgentCoreGatewayTargetHandler(mockRequestHandler);
+        mockContext = {
+            clientContext: {
+                Custom: {
+                    bedrockagentcoreToolName: "test_tool",
+                },
+            },
+        };
+    });
+    it("should handle valid tool invocation", async () => {
+        const expectedResponse = {
+            jsonrpc: "2.0",
+            result: { message: "Tool executed successfully" },
+            id: 1,
+        };
+        mockRequestHandler.setResponse("tools/call", expectedResponse);
+        const event = { param1: "value1", param2: "value2" };
+        const result = await handler.handleEvent(event, mockContext);
+        expect(result).toEqual({ message: "Tool executed successfully" });
+    });
+    it("should throw error when tool name is missing", async () => {
+        const contextWithoutTool = { clientContext: { Custom: {} } };
+        const event = { param1: "value1" };
+        await expect(handler.handleEvent(event, contextWithoutTool)).rejects.toThrow("Missing bedrockagentcoreToolName in context");
+    });
+    it("should throw error when request handler returns error", async () => {
+        const errorResponse = {
+            jsonrpc: "2.0",
+            error: { code: -32601, message: "Method not found" },
+            id: 1,
+        };
+        mockRequestHandler.setResponse("tools/call", errorResponse);
+        const event = { param1: "value1" };
+        await expect(handler.handleEvent(event, mockContext)).rejects.toThrow("Method not found");
+    });
+});

package/dist/handlers/index.d.ts

@@ -2,3 +2,4 @@ export { RequestHandler } from "./requestHandler.js";
 export { APIGatewayProxyEventHandler } from "./apiGatewayProxyEventHandler.js";
 export { APIGatewayProxyEventV2Handler } from "./apiGatewayProxyEventV2Handler.js";
 export { LambdaFunctionURLEventHandler } from "./lambdaFunctionUrlEventHandler.js";
+export { BedrockAgentCoreGatewayTargetHandler } from "./bedrockAgentCoreGatewayTargetHandler.js";

package/dist/handlers/index.js

@@ -1,3 +1,4 @@
 export { APIGatewayProxyEventHandler } from "./apiGatewayProxyEventHandler.js";
 export { APIGatewayProxyEventV2Handler } from "./apiGatewayProxyEventV2Handler.js";
 export { LambdaFunctionURLEventHandler } from "./lambdaFunctionUrlEventHandler.js";
+export { BedrockAgentCoreGatewayTargetHandler } from "./bedrockAgentCoreGatewayTargetHandler.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aws/run-mcp-servers-with-aws-lambda",
   "description": "Run Model Context Protocol (MCP) servers with AWS Lambda",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "type": "module",
   "license": "Apache-2.0",
   "author": {