Model Context Protocol (MCP) on AWS: The New Architecture for Enterprise AI Agent Integrations

On this page

Sixteen months after Anthropic published the Model Context Protocol, the question for most AWS teams is no longer whether to expose internal systems to agents through MCP, but where the protocol should terminate. Write an MCP server and host it yourself, run it on a managed runtime, or let a managed gateway speak MCP while your code stays a plain Lambda function: each choice moves authentication, session handling and upgrade work to a different owner.

By March 2026 AWS offers all three. Amazon Bedrock AgentCore has been generally available since October 2025, its Gateway turns Lambda functions and API definitions into MCP tools, its Runtime hosts MCP servers in isolated microVMs, and since 10 March 2026 that Runtime also supports the stateful parts of the protocol. Amazon Q Developer has been an MCP client since April 2025, and in February 2026 the Bedrock Responses API learned to call Gateway tools server-side.

This article explains what the protocol actually standardises, compares the three hosting patterns with working code for the first two, and covers the security rules that the protocol itself makes mandatory. The code targets the 2025-11-25 revision of the specification and the official Python SDK, version 1.26.0.

Protocol basics

MCP is JSON-RPC 2.0 between a client, which lives inside an AI application, and a server, which exposes capabilities. A server can offer three kinds of primitive: tools, which the model can call; resources, which are readable data addressed by URI; and prompts, which are reusable templates. Clients can in turn offer sampling (the server asks the client’s model for a completion), elicitation (the server asks the user for input) and roots. A session starts with an initialize exchange in which both sides agree a protocol version and declare their capabilities.

The specification defines two standard transports. stdio runs the server as a subprocess of the client and is what IDE plugins and desktop apps mostly use. Streamable HTTP exposes a single endpoint, conventionally /mcp, that accepts each client message as an HTTP POST; the server answers with either one JSON object or a Server-Sent Events stream. Streamable HTTP replaced the older HTTP+SSE transport in the 2025-03-26 revision, so any design that still describes MCP as “HTTP plus SSE” is describing a deprecated transport.

ℹ️
PROTOCOL VERSION

The current revision on 22 March 2026 is 2025-11-25. It added Client ID Metadata Documents for OAuth client registration, URL-mode elicitation, icons, and experimental tasks for long-running requests. Over HTTP, clients send the negotiated version in an MCP-Protocol-Version header on every request after initialisation, and a server must reject versions it does not support with HTTP 400.

Streamable HTTP has an optional session: a server may return an MCP-Session-Id header from initialize, and the client must then send it on every request. A server that does not issue one is stateless: every POST stands alone, so any instance behind a load balancer can answer it. That property decides most of what follows, because stateless servers fit Lambda and horizontally scaled containers, while sampling, elicitation and server-initiated notifications need a session that lives somewhere.

Hosting options on AWS

Diagram of three MCP hosting patterns on AWS: AgentCore Gateway with a Lambda target, AgentCore Runtime hosting a FastMCP server, and a self-hosted MCP server behind API Gateway
The same tools can be exposed through a managed MCP gateway, a managed MCP server host, or an endpoint you run yourself. Each moves authentication and protocol upgrades to a different owner.
PatternWho speaks MCPYour codeInbound auth
AgentCore Gateway with a Lambda targetThe gatewayA plain Lambda handlerGateway JWT authorizer (OAuth)
AgentCore Runtime hosting an MCP serverYour server, in a microVM per sessionAn MCP SDK server in an ARM64 containerRuntime: SigV4 or OAuth
Self-hosted on Lambda, ECS or EKSYour serverAn MCP SDK server plus its HTTP edgeWhatever you build

AgentCore Gateway can also front OpenAPI and Smithy definitions, existing MCP servers, and, since December 2025, Amazon API Gateway REST APIs. When the tool logic already exists as an API, the gateway removes the need to write an MCP server at all.

AgentCore Gateway with a Lambda target

The gateway presents one MCP endpoint to clients, handles tools/list and tools/call, authenticates callers with a JWT authorizer, and invokes targets with its own IAM role. For a Lambda target it passes the tool arguments as the event and the tool name in context.client_context.custom["bedrockAgentCoreToolName"], prefixed with the target name and three underscores. The function contains no MCP code.

%%{init: {'theme': 'base', 'themeVariables': {'actorBkg': '#FFF3E0', 'actorBorder': '#FF9900', 'actorTextColor': '#232F3E', 'signalColor': '#0073BB', 'signalTextColor': '#0F172A', 'noteBkgColor': '#FFF8E7', 'noteBorderColor': '#FF9900', 'noteTextColor': '#232F3E'}}}%%
sequenceDiagram
    participant C as MCP client
    participant G as AgentCore Gateway
    participant L as Lambda target
    participant D as DynamoDB
    C->>G: POST /mcp tools/call (Bearer JWT)
    Note over G: Validate JWT issuer, audience, client
    G->>L: Invoke with arguments, tool name in client context
    L->>D: Query one customer partition
    D-->>L: Items (one page)
    L-->>G: Bounded JSON result
    G-->>C: tools/call result

The tool schema is registered with the target, not discovered from the function. This is the schema for the sample’s two read-only tools:

JSON38 lines
[
  {
    "name": "get_customer_summary",
    "description": "Return the order count and total spend in EUR for one customer. Use this before listing orders when the user asks how much a customer has spent.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "customer_id": {
          "type": "string",
          "description": "Customer identifier in the form C-123456"
        }
      },
      "required": ["customer_id"]
    }
  },
  {
    "name": "list_customer_orders",
    "description": "Return one page of a customer's orders, newest first. Pass next_token from the previous result to get the next page. At most 25 orders are returned per call.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "customer_id": {
          "type": "string",
          "description": "Customer identifier in the form C-123456"
        },
        "limit": {
          "type": "integer",
          "description": "Orders per page, 1 to 25. Defaults to 10."
        },
        "next_token": {
          "type": "string",
          "description": "Opaque token from the previous page. Omit for the first page."
        }
      },
      "required": ["customer_id"]
    }
  }
]

And the complete handler. Business logic lives in a shared sales_tools module, which validates the customer id, clamps page size to 25 and binds pagination tokens to one customer; it is in the sample repository linked below.

Python70 lines
"""AWS Lambda target for an Amazon Bedrock AgentCore Gateway.

AgentCore Gateway speaks MCP to the client. For a Lambda target it invokes
this function with the tool arguments as the event, and puts the tool name in
context.client_context.custom["bedrockAgentCoreToolName"], prefixed with the
target name and a triple underscore. The function itself contains no MCP code.
"""

from __future__ import annotations

import json
import logging
import os
import sys
from typing import Any, Callable

# Allow `sales_tools` to be packaged next to this file or one level up.
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

import sales_tools  # noqa: E402

logger = logging.getLogger()
logger.setLevel(os.environ.get("LOG_LEVEL", "INFO"))

TOOL_NAME_DELIMITER = "___"

TOOLS: dict[str, Callable[..., dict[str, Any]]] = {
    "get_customer_summary": lambda args: sales_tools.get_customer_summary(
        args.get("customer_id")
    ),
    "list_customer_orders": lambda args: sales_tools.list_customer_orders(
        args.get("customer_id"),
        args.get("limit", 10),
        args.get("next_token"),
    ),
}


def _tool_name(context: Any) -> str:
    custom = getattr(getattr(context, "client_context", None), "custom", None) or {}
    qualified = custom.get("bedrockAgentCoreToolName", "")
    if TOOL_NAME_DELIMITER in qualified:
        return qualified.split(TOOL_NAME_DELIMITER, 1)[1]
    return qualified


def _log(level: int, message: str, **fields: Any) -> None:
    logger.log(level, json.dumps({"message": message, **fields}, default=str))


def lambda_handler(event: dict[str, Any], context: Any) -> dict[str, Any]:
    tool = _tool_name(context)
    request_id = getattr(context, "aws_request_id", None)
    handler = TOOLS.get(tool)
    if handler is None:
        _log(logging.WARNING, "unknown tool", tool=tool, request_id=request_id)
        return {"error": "UNKNOWN_TOOL", "message": f"Unknown tool: {tool}"}

    try:
        result = handler(event or {})
    except sales_tools.ToolInputError as exc:
        # Input errors go back to the model so it can correct the call.
        _log(logging.INFO, "invalid input", tool=tool, request_id=request_id, error=str(exc))
        return {"error": "INVALID_INPUT", "message": str(exc)}
    except Exception:  # noqa: BLE001 - never leak internals to the model
        logger.exception(json.dumps({"message": "tool failed", "tool": tool, "request_id": request_id}))
        return {"error": "INTERNAL_ERROR", "message": "The tool failed. Try again later."}

    _log(logging.INFO, "tool succeeded", tool=tool, request_id=request_id)
    return result

Input errors are returned to the model as data so it can correct the call; anything unexpected is logged with the request id and returned as a generic message, so stack traces and table names never reach the model’s context.

AgentCore Runtime hosting an MCP server

When you need resources, prompts or, since March 2026, elicitation and sampling, you need a real MCP server. AgentCore Runtime runs it as an ARM64 container and expects Streamable HTTP on 0.0.0.0:8000/mcp. For protocol versions up to 2025-11-25 the documented default is stateless mode; stateful mode, released on 10 March 2026, gives each user session its own microVM and preserves the MCP session between requests.

Python66 lines
"""MCP server for Amazon Bedrock AgentCore Runtime (or any container host).

AgentCore Runtime expects a stateless Streamable HTTP MCP server listening on
0.0.0.0:8000 at the /mcp path. Built on the official MCP Python SDK, pinned
to mcp==1.26.0.
"""

from __future__ import annotations

import logging
import os
import sys
from typing import Any

sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

from mcp.server.fastmcp import FastMCP  # noqa: E402
from mcp.server.fastmcp.exceptions import ToolError  # noqa: E402

import sales_tools  # noqa: E402

logging.basicConfig(level=os.environ.get("LOG_LEVEL", "INFO"))
logger = logging.getLogger("sales-mcp")

mcp = FastMCP(
    "sales-data",
    host=os.environ.get("MCP_HOST", "0.0.0.0"),
    port=int(os.environ.get("MCP_PORT", "8000")),
    stateless_http=True,
)


def _call(fn, *args) -> dict[str, Any]:
    try:
        return fn(*args)
    except sales_tools.ToolInputError as exc:
        # Raised as a tool error, so the client receives isError=true
        # and the model can correct its arguments.
        raise ToolError(str(exc)) from exc
    except Exception as exc:  # noqa: BLE001 - never leak internals to the model
        logger.exception("tool failed")
        raise ToolError("The tool failed. Try again later.") from exc


@mcp.tool()
def get_customer_summary(customer_id: str) -> dict[str, Any]:
    """Return the order count and total spend in EUR for one customer.

    customer_id: customer identifier in the form C-123456.
    """
    return _call(sales_tools.get_customer_summary, customer_id)


@mcp.tool()
def list_customer_orders(
    customer_id: str, limit: int = 10, next_token: str | None = None
) -> dict[str, Any]:
    """Return one page of a customer's orders, newest first (at most 25).

    Pass next_token from the previous result to get the next page.
    """
    return _call(sales_tools.list_customer_orders, customer_id, limit, next_token)


if __name__ == "__main__":
    mcp.run(transport="streamable-http")

FastMCP builds the input schema for each tool from the type hints and the docstring becomes the tool description, so the docstring is part of your interface and is read by the model. Raising ToolError returns a result with isError set to true instead of a protocol error, which is what the specification asks for when the failure is something the model can fix.

The Runtime handles inbound authentication (SigV4 for IAM callers, or OAuth with a discovery URL) before a request reaches the container. Run outside AgentCore, the same server has no authentication at all and must not be exposed without an authenticating proxy in front of it.

Self-hosted on Lambda

Running an MCP server in your own Lambda function remains an option where AgentCore is not available in your Region or your platform rules require it. The awslabs project run-model-context-protocol-servers-with-aws-lambda wraps existing stdio servers so that each Lambda invocation is one short-lived MCP exchange, and a stateless FastMCP app can also run behind the AWS Lambda Web Adapter. In both cases you own what the managed options provide: OAuth protected-resource metadata, token validation, throttling, and the upgrade to each new protocol revision.

Lambda suits stateless tool servers. It does not suit sampling, elicitation or server-sent notifications, because those need a session that outlives a single invocation; for those, use Runtime or a container service with sticky sessions.

Clients on AWS

  • Amazon Q Developer: MCP tools and prompts in the CLI since 29 April 2025 (stdio), in the VS Code and JetBrains plugins since 13 June 2025, remote HTTP servers with OAuth since 18 September 2025, and administrator allow-lists since 28 August 2025.
  • Bedrock Responses API: since 24 February 2026 a request can name an AgentCore Gateway as an MCP tool source; Bedrock discovers the tools, lets the model choose, and runs the calls server-side in the same API call.
  • Agent frameworks: Strands Agents, LangGraph and others connect to any Streamable HTTP endpoint, including Gateway and Runtime.
  • Amazon Bedrock Agents: there is no native MCP endpoint discovery in action groups. The April 2025 pattern uses the Inline Agent SDK and return of control, so the MCP calls happen in your client code. Treat it as a bridge, not as server-side MCP support.

Security

MCP authorization is optional for stdio servers but defined for HTTP: the MCP server is an OAuth 2.1 resource server, must publish Protected Resource Metadata (RFC 9728), and must accept only tokens issued for itself, which clients request with the RFC 8707 resource parameter. Gateway and Runtime implement the inbound side of this for you.

⚠️
TOKEN PASSTHROUGH

Do not forward the user’s access token from the MCP client to downstream APIs. The 2025-11-25 authorization specification says an MCP server must not pass through the token it received, and the security best practices name token passthrough as explicitly forbidden: the downstream API cannot tell which client called, and audience checks are bypassed. Give the server its own credentials (an IAM role, or an OAuth token issued to the server for the downstream API) and enforce per-user rules from validated claims.

  • Least privilege per tool. The sample’s Lambda role needs dynamodb:Query on one table. Separate read and write tools into separate functions or targets with separate roles, so a prompt-injected model cannot reach a write path through a read tool.
  • Treat tool descriptions as code. The model reads them. Review them like code and do not load descriptions from data a user can edit.
  • Treat tool output as untrusted input. Text that a tool returns from a database or a web page can carry instructions. Return structured fields rather than free text where you can.
  • Validate every argument. The sample rejects any customer id that does not match C- plus six digits before it reaches DynamoDB, and rejects pagination tokens issued for another customer.
⚖️
REGULATED DATA

With personal or health data in scope, keep tool results to the minimum fields the task needs and log tool calls with the caller identity, tool name and request id, not the payload. Data a tool returns enters the model’s context and may be retained by the client application, so redaction belongs in the tool, before the result leaves your account. This sample uses synthetic data only.

Context budget

A tool result goes into the model’s context. A query that returns every row will fill the context window, raise the cost of every later turn, and push the user’s instructions further from the model’s attention. Bound every result in the tool, not in the prompt:

  • Clamp page size on the server (25 in the sample), whatever the model asks for.
  • Return an opaque next_token and describe it in the tool description, so the model knows how to ask for more.
  • Offer a summary tool (get_customer_summary) so the common question does not need the raw rows at all.

Cost

AgentCore Gateway charges $0.005 per 1,000 MCP operations such as tools/list and tools/call, $0.025 per 1,000 semantic tool searches, and $0.02 per 100 tools indexed per month. AgentCore Runtime bills per second for vCPU at $0.0895 per vCPU-hour and memory at $0.00945 per GB-hour, and does not bill CPU while the process waits on I/O.

One million tool calls a monthAssumptionMonthly cost
Gateway operations1,000,000 tools/call at $0.005 per 1,000$5.00
Lambda requests1,000,000 at $0.20 per million$0.20
Lambda computearm64, 256 MB, 100 ms each: 25,000 GB-s at $0.0000133334$0.33
Total before DynamoDB and data transferFree tier ignored$5.53

Worked cell: 1,000,000 × 0.1 s × 0.25 GB = 25,000 GB-seconds, and 25,000 × $0.0000133334 = $0.33. The gateway fee dominates, and it is still small next to the model tokens that the same million calls consume. The tools/list calls that clients make at session start add to the gateway count, so cache tool lists in long-lived clients.

Production considerations

  • Version the tool schema. Renaming a tool or a required argument breaks every agent prompt that mentions it. Add new tools; deprecate old ones with a description change before removing them.
  • Observability. Log one structured line per tool call with tool name, request id, latency and outcome. Gateway and Runtime emit to CloudWatch, and AgentCore Observability accepts OpenTelemetry traces from agent frameworks.
  • Timeouts. Keep tool latency well inside the client’s request timeout. Long work belongs in an asynchronous job that a second tool polls.
  • Regions. AgentCore was available in nine Regions at general availability; stateful MCP on Runtime launched in fourteen. Check your Region before choosing the pattern.

Decision framework

Decision matrix comparing AgentCore Gateway with a Lambda target, a Runtime-hosted MCP server and a self-hosted MCP server across protocol code, authentication, existing APIs, resources and prompts, elicitation and Region coverage
Gateway with Lambda targets covers most tool-only integrations. Runtime is the choice when you need resources, prompts or stateful features. Self-hosting trades managed security for Region and platform freedom.

Start with AgentCore Gateway and Lambda targets when your tools are request-response lookups or actions over systems you already own: there is no MCP code to upgrade and authentication is configuration. Move a server to AgentCore Runtime when it needs resources, prompts, elicitation or sampling, or when you are hosting an existing open-source MCP server. Self-host only when AgentCore is not available in your Region or a platform constraint rules it out, and budget for building the OAuth resource-server side yourself.

The decision flips if most of your tools already sit behind OpenAPI or API Gateway: point a gateway target at the API definition and write no Lambda code either.

📝
HOW THIS WAS CHECKED

The two samples were run with Python 3.13 and the official MCP Python SDK mcp==1.26.0 (released 24 January 2026), against a synthetic DynamoDB table in moto. Six tests pass: the Lambda handler is called with the AgentCore Gateway event and client-context shape, and the FastMCP server is started over Streamable HTTP and called with the official MCP client, which negotiated protocol version 2025-11-25. Totals are checked against a sum computed independently from the fixture. Deployment to AWS was not part of the test run. AgentCore and Lambda prices were read from the AWS pricing pages in November 2026.

Key takeaways

  • MCP standardises JSON-RPC between AI clients and tool servers; Streamable HTTP replaced HTTP+SSE in March 2025, and 2025-11-25 is the current revision.
  • On AWS the main decision is where the protocol terminates: AgentCore Gateway (no MCP code), AgentCore Runtime (your MCP server, managed hosting) or your own endpoint.
  • Gateway with Lambda targets covers most tool-only integrations; Runtime covers resources, prompts and, since March 2026, stateful features.
  • Token passthrough is forbidden by the specification. Validate tokens issued for the MCP server and give the server its own downstream credentials.
  • Bound every tool result in code: clamp page size, return a continuation token and offer summary tools.

Which pattern are you running your MCP tools on, and what pushed you there? Share it in the comments.

Glossary

Model Context Protocol (MCP)
An open protocol, JSON-RPC 2.0 based, for connecting AI applications to tools, data and prompts.
MCP client
The component inside an AI application that connects to one MCP server and relays its capabilities to the model.
MCP server
A program that exposes tools, resources and prompts to MCP clients.
Streamable HTTP
The MCP HTTP transport: one endpoint, each client message a POST, responses as JSON or an SSE stream.
Stateless server
A Streamable HTTP server that issues no session id, so any instance can answer any request.
Elicitation
A server request that asks the user, through the client, for more input during a tool call.
Sampling
A server request that asks the client’s model for a completion.
AgentCore Gateway
A managed AWS service that exposes Lambda functions, API definitions and MCP servers as tools on one MCP endpoint.
AgentCore Runtime
A managed AWS service that runs agents and MCP servers in isolated microVMs per session.
Protected Resource Metadata
The RFC 9728 document an MCP server publishes to tell clients which authorization server issues its tokens.
Token passthrough
Forwarding a client’s access token to a downstream API unchanged; forbidden by the MCP specification.

References & Further Reading


Discover more from C4: Container, Code, Cloud & Context

Subscribe to get the latest posts sent to your email.

Written by

Nithin Mohan TK

Hello Namaste! 👋🏻 I'm an accomplished Enterprise Solution Architect & Engineering Leader with 20+ years of progressive experience architecting, building, and scaling transformative enterprise solutions. ⚜️ Solution Architect / AI & Cloud 📌 Galway, Ireland

Leave a comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.