@aws/run-mcp-servers-with-aws-lambda 0.3.5 → 0.4.1

package/README.md

@@ -43,11 +43,12 @@ 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.
 
 ## Use API Gateway
 
@@ -155,7 +156,7 @@ from mcp.client.streamable_http import streamablehttp_client
 # Create OAuth client provider here
 
 async with streamablehttp_client(
-    url="https://abc123.execute-api.us-east-2.amazonaws.com/prod/mcp",
+    url="https://abc123.execute-api.us-west-2.amazonaws.com/prod/mcp",
     auth=oauth_client_provider,
 ) as (
     read_stream,
@@ -194,7 +195,172 @@ const client = new Client(
 // Create OAuth client provider here
 
 const transport = new StreamableHTTPClientTransport(
-  "https://abc123.execute-api.us-east-2.amazonaws.com/prod/mcp",
+  "https://abc123.execute-api.us-west-2.amazonaws.com/prod/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 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-building-lambda-multiple-tools).
+AgentCore Gateway can then advertise the schema to HTTP clients and validate request inputs and outputs.
+
+To retrieve and save your stdio-based MCP server's tool schema to a file, run:
+
+```bash
+npx @modelcontextprotocol/inspector --cli --method tools/list <your MCP server command and arguments> > tool-schema.json
+
+# For example:
+npx @modelcontextprotocol/inspector --cli --method tools/list uvx mcp-server-time > tool-schema.json
+```
+
+<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)
+```
+
+See a full, deployable example [here](examples/servers/book-search/).
+
+</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: Record<string, unknown>,
+  context: Context
+): Promise<Record<string, unknown>> => {
+  return requestHandler.handle(event, context);
+};
+```
+
+See a full, deployable example [here](examples/servers/dictionary/).
+
+</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,
   }
@@ -307,9 +473,9 @@ from mcp import ClientSession
 from mcp_lambda.client.streamable_http_sigv4 import streamablehttp_client_with_sigv4
 
 async with streamablehttp_client_with_sigv4(
-    url="https://url-id-12345.lambda-url.us-east-2.on.aws",
+    url="https://url-id-12345.lambda-url.us-west-2.on.aws",
     service="lambda",
-    region="us-east-2",
+    region="us-west-2",
 ) as (
     read_stream,
     write_stream,
@@ -345,10 +511,10 @@ const client = new Client(
 );
 
 const transport = new StreamableHTTPClientWithSigV4Transport(
-  new URL("https://url-id-12345.lambda-url.us-east-2.on.aws"),
+  new URL("https://url-id-12345.lambda-url.us-west-2.on.aws"),
   {
     service: "lambda",
-    region: "us-east-2",
+    region: "us-west-2",
   }
 );
 await client.connect(transport);
@@ -441,7 +607,7 @@ from mcp_lambda import LambdaFunctionParameters, lambda_function_client
 
 server_params = LambdaFunctionParameters(
     function_name="my-mcp-server-function",
-    region_name="us-east-2",
+    region_name="us-west-2",
 )
 
 async with lambda_function_client(server_params) as (
@@ -470,7 +636,7 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 
 const serverParams: LambdaFunctionParameters = {
   functionName: "my-mcp-server-function",
-  regionName: "us-east-2",
+  regionName: "us-west-2",
 };
 
 const client = new Client(

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
+     */
+    handle(event: Record<string, unknown>, context: Context): Promise<unknown>;
+}

package/dist/handlers/bedrockAgentCoreGatewayTargetHandler.js

@@ -0,0 +1,48 @@
+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 handle(event, context) {
+        // Extract tool metadata from context
+        const clientContext = context.clientContext;
+        const custom = clientContext?.["custom"];
+        const gatewayToolName = custom?.["bedrockAgentCoreToolName"];
+        if (!gatewayToolName) {
+            throw new Error("Missing bedrockAgentCoreToolName in context");
+        }
+        // Gateway names the tools like <target name>___<tool name>
+        const delimiter = "___";
+        const delimiterIndex = gatewayToolName.indexOf(delimiter);
+        if (delimiterIndex === -1) {
+            throw new Error(`Invalid gateway tool name format: ${gatewayToolName}`);
+        }
+        const toolName = gatewayToolName.substring(delimiterIndex + delimiter.length);
+        // 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,16 +1,21 @@
 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();
     shouldThrow = false;
+    lastCall = null;
     setResponse(method, response) {
         this.responses.set(method, response);
     }
     setShouldThrow(shouldThrow) {
         this.shouldThrow = shouldThrow;
     }
+    getLastCall() {
+        return this.lastCall;
+    }
     async handleRequest(request, _context) {
+        this.lastCall = request;
         if (this.shouldThrow) {
             throw new Error("Mock handler error");
         }
@@ -627,3 +632,80 @@ 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: "target___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.handle(event, mockContext);
+        expect(result).toEqual({ message: "Tool executed successfully" });
+        // Verify the extracted tool name is everything after the first delimiter
+        const lastCall = mockRequestHandler.getLastCall();
+        expect(lastCall?.params?.name).toBe("test_tool");
+    });
+    it("should throw error when tool name is missing", async () => {
+        const contextWithoutTool = { clientContext: { custom: {} } };
+        const event = { param1: "value1" };
+        await expect(handler.handle(event, contextWithoutTool)).rejects.toThrow("Missing bedrockAgentCoreToolName in context");
+    });
+    it("should throw error when tool name format is invalid", async () => {
+        const contextWithInvalidFormat = {
+            clientContext: {
+                custom: {
+                    bedrockAgentCoreToolName: "invalid_format",
+                },
+            },
+        };
+        const event = { param1: "value1" };
+        await expect(handler.handle(event, contextWithInvalidFormat)).rejects.toThrow("Invalid gateway tool name format: invalid_format");
+    });
+    it("should handle tool name with multiple delimiters", async () => {
+        const contextWithMultipleDelimiters = {
+            clientContext: {
+                custom: {
+                    bedrockAgentCoreToolName: "target___test___tool",
+                },
+            },
+        };
+        const expectedResponse = {
+            jsonrpc: "2.0",
+            result: { message: "Tool executed successfully" },
+            id: 1,
+        };
+        mockRequestHandler.setResponse("tools/call", expectedResponse);
+        const event = { param1: "value1" };
+        const result = await handler.handle(event, contextWithMultipleDelimiters);
+        expect(result).toEqual({ message: "Tool executed successfully" });
+        // Verify the extracted tool name is everything after the first delimiter
+        const lastCall = mockRequestHandler.getLastCall();
+        expect(lastCall?.params?.name).toBe("test___tool");
+    });
+    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.handle(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.5",
+  "version": "0.4.1",
   "type": "module",
   "license": "Apache-2.0",
   "author": {
@@ -39,29 +39,29 @@
     "dist"
   ],
   "devDependencies": {
-    "@eslint/js": "^9.32.0",
+    "@eslint/js": "^9.33.0",
     "@tsconfig/recommended": "^1.0.10",
     "@types/aws-lambda": "^8.10.152",
     "@types/jest": "^30.0.0",
-    "@types/node": "^24.1.0",
+    "@types/node": "^24.3.0",
     "aws-sdk-client-mock": "^4.1.0",
     "aws-sdk-client-mock-jest": "^4.1.0",
-    "eslint": "^9.30.1",
+    "eslint": "^9.33.0",
     "eslint-plugin-check-file": "^3.3.0",
     "jest": "^30.0.5",
-    "ts-jest": "^29.4.0",
-    "tsx": "^4.20.3",
+    "ts-jest": "^29.4.1",
+    "tsx": "^4.20.4",
     "typescript": "^5.9.2",
-    "typescript-eslint": "^8.39.0"
+    "typescript-eslint": "^8.40.0"
   },
   "dependencies": {
     "@aws-crypto/sha256-js": "^5.2.0",
-    "@aws-sdk/client-lambda": "^3.859.0",
+    "@aws-sdk/client-lambda": "^3.873.0",
     "@aws-sdk/credential-provider-node": "^3.859.0",
     "@aws-sdk/protocol-http": "^3.374.0",
     "@aws-sdk/types": "^3.840.0",
-    "@modelcontextprotocol/sdk": "^1.17.1",
-    "@smithy/signature-v4": "^5.1.2",
+    "@modelcontextprotocol/sdk": "^1.17.4",
+    "@smithy/signature-v4": "^5.1.3",
     "winston": "^3.17.0"
   }
 }