feat: support for Bedrock AgentCore Gateway Lambda targets

Author: clareliguori

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
 
@@ -206,6 +207,158 @@ See a full example as part of the sample chatbot [here](examples/chatbots/typesc
 
 </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.
+
+Using Bedrock AgentCore Gateway in front of your stdio-based MCP server requires that
+you duplicate the MCP server's input schema (and optionally, the output schema), and
+provide it in the AgentCore Gateway Lambda target configuration. AgentCore Gateway
+can then advertise the schema to HTTP clients and validate request inputs and outputs.
+
+You can choose your desired OAuth server provider for this solution, such as Amazon Cognito,
+Okta, or Auth0.
+
+<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

src/python/src/mcp_lambda/handlers/__init__.py

@@ -7,22 +7,29 @@
 - RequestHandler: Interface for handling individual JSON-RPC requests
 - StreamableHttpHandler: Base class handling MCP protocol specifics
 - APIGatewayProxyEventHandler: Handler for API Gateway V1 events
-- APIGatewayProxyEventV2Handler: Handler for API Gateway V2 events  
+- APIGatewayProxyEventV2Handler: Handler for API Gateway V2 events
 - LambdaFunctionURLEventHandler: Handler for Lambda Function URL events
+- BedrockAgentCoreGatewayTargetHandler: Handler for Bedrock AgentCore Gateway events
 """
 
 from .api_gateway_proxy_event_handler import APIGatewayProxyEventHandler
 from .api_gateway_proxy_event_v2_handler import APIGatewayProxyEventV2Handler
+from .bedrock_agent_core_gateway_handler import BedrockAgentCoreGatewayTargetHandler
 from .lambda_function_url_event_handler import LambdaFunctionURLEventHandler
 from .request_handler import RequestHandler
-from .streamable_http_handler import HttpResponse, ParsedHttpRequest, StreamableHttpHandler
+from .streamable_http_handler import (
+    HttpResponse,
+    ParsedHttpRequest,
+    StreamableHttpHandler,
+)
 
 __all__ = [
     "RequestHandler",
-    "StreamableHttpHandler", 
+    "StreamableHttpHandler",
     "ParsedHttpRequest",
     "HttpResponse",
     "APIGatewayProxyEventHandler",
-    "APIGatewayProxyEventV2Handler", 
+    "APIGatewayProxyEventV2Handler",
     "LambdaFunctionURLEventHandler",
+    "BedrockAgentCoreGatewayTargetHandler",
 ]

src/python/src/mcp_lambda/handlers/bedrock_agent_core_gateway_handler.py

@@ -0,0 +1,47 @@
+from typing import Any, Dict
+
+from aws_lambda_powertools.utilities.typing import LambdaContext
+from mcp.types import JSONRPCError, JSONRPCRequest
+
+from .request_handler import RequestHandler
+
+
+class BedrockAgentCoreGatewayTargetHandler:
+    """
+    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.
+    """
+
+    def __init__(self, request_handler: RequestHandler):
+        self.request_handler = request_handler
+
+    def handle_event(self, event: Dict[str, Any], context: LambdaContext) -> Any:
+        """Handle Lambda invocation from Bedrock AgentCore Gateway"""
+        # Extract tool metadata from context
+        tool_name = None
+        if context.client_context and hasattr(context.client_context, "custom"):
+            tool_name = context.client_context.custom.get("bedrockagentcoreToolName")
+
+        if not tool_name:
+            raise ValueError("Missing bedrockagentcoreToolName in context")
+
+        # Create JSON-RPC request from gateway event
+        jsonrpc_request = JSONRPCRequest(
+            jsonrpc="2.0",
+            id=1,
+            method="tools/call",
+            params={
+                "name": tool_name,
+                "arguments": event,
+            },
+        )
+
+        result = self.request_handler.handle_request(jsonrpc_request, context)
+
+        if isinstance(result, JSONRPCError):
+            raise Exception(result.error.message)
+
+        return result.result

src/python/tests/test_handlers.py

@@ -20,6 +20,7 @@
 from mcp_lambda.handlers import (
     APIGatewayProxyEventHandler,
     APIGatewayProxyEventV2Handler,
+    BedrockAgentCoreGatewayTargetHandler,
     LambdaFunctionURLEventHandler,
     RequestHandler,
 )
@@ -509,3 +510,74 @@ def create_event(self, method="POST", headers=None, body=None):
             },
             "isBase64Encoded": False,
         }
+
+
+class TestBedrockAgentCoreGatewayTargetHandler:
+    """Test cases for BedrockAgentCoreGatewayTargetHandler."""
+
+    def test_handle_valid_tool_invocation(self):
+        """Test handling valid tool invocation."""
+        # Create a mock request handler that handles tools/call
+        mock_handler = Mock(spec=RequestHandler)
+        mock_handler.handle_request.return_value = JSONRPCResponse(
+            jsonrpc="2.0",
+            result={"message": "Tool executed successfully"},
+            id=1,
+        )
+
+        handler = BedrockAgentCoreGatewayTargetHandler(mock_handler)
+
+        # Mock context with tool name
+        context = Mock(spec=LambdaContext)
+        context.client_context = Mock()
+        context.client_context.custom = {"bedrockagentcoreToolName": "test_tool"}
+
+        event = {"param1": "value1", "param2": "value2"}
+        result = handler.handle_event(event, context)
+
+        assert result == {"message": "Tool executed successfully"}
+
+        # Verify the request was properly constructed
+        call_args = mock_handler.handle_request.call_args[0]
+        request = call_args[0]
+        assert request.method == "tools/call"
+        assert request.params["name"] == "test_tool"
+        assert request.params["arguments"] == event
+
+    def test_missing_tool_name_raises_error(self):
+        """Test that missing tool name raises ValueError."""
+        handler = BedrockAgentCoreGatewayTargetHandler(Mock(spec=RequestHandler))
+
+        # Mock context without tool name
+        context = Mock(spec=LambdaContext)
+        context.client_context = Mock()
+        context.client_context.custom = {}
+
+        event = {"param1": "value1"}
+
+        with pytest.raises(
+            ValueError, match="Missing bedrockagentcoreToolName in context"
+        ):
+            handler.handle_event(event, context)
+
+    def test_request_handler_error_raises_exception(self):
+        """Test that request handler errors are raised as exceptions."""
+        # Create a mock request handler that returns an error
+        mock_handler = Mock(spec=RequestHandler)
+        mock_handler.handle_request.return_value = JSONRPCError(
+            jsonrpc="2.0",
+            error=ErrorData(code=METHOD_NOT_FOUND, message="Tool not found"),
+            id=1,
+        )
+
+        handler = BedrockAgentCoreGatewayTargetHandler(mock_handler)
+
+        # Mock context with tool name
+        context = Mock(spec=LambdaContext)
+        context.client_context = Mock()
+        context.client_context.custom = {"bedrockagentcoreToolName": "unknown_tool"}
+
+        event = {"param1": "value1"}
+
+        with pytest.raises(Exception, match="Tool not found"):
+            handler.handle_event(event, context)

src/typescript/src/handlers/bedrockAgentCoreGatewayHandler.ts

@@ -0,0 +1,55 @@
+import { Context } from "aws-lambda";
+import {
+  JSONRPCRequest,
+  isJSONRPCError,
+} from "@modelcontextprotocol/sdk/types.js";
+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 class BedrockAgentCoreGatewayTargetHandler {
+  constructor(private requestHandler: RequestHandler) {}
+
+  /**
+   * Handle Lambda invocation from Bedrock AgentCore Gateway
+   */
+  async handleEvent(
+    event: Record<string, unknown>,
+    context: Context
+  ): Promise<unknown> {
+    // 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: 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;
+  }
+}