Guidance for Deploying Model Context Protocol (MCP) Servers on AWS

This guidance provides a pattern for deploying Model Context Protocol (MCP) servers on AWS using secure authentication via Amazon Cognito. It implements the 2025-06-18 MCP specification with OAuth 2.0 Protected Resource Metadata (RFC9728).

Key architectural components include:

• CloudFront & WAF: Global delivery and security.
• Application Load Balancer (ALB): Traffic distribution and SSL termination.
• ECS Fargate & Lambda: Containerized and serverless hosting for MCP servers.
• Amazon Cognito: Acts as the OAuth 2.0 authorization server.
• StreamableHTTP transport: Enables remote access via stateless request handling.

The deployment is organized into four CDK stacks: VPC, Security, CloudFront WAF, and MCP Server stacks.

A production-ready deployment on AWS involves several CDK stacks to manage networking, security, and compute:

• VPC Stack: Manages the VPC, subnets, and security groups.
• Security Stack: Provisions the AWS Cognito User Pool and App Client.
• CloudFront WAF Stack: Deploys a WAF Web ACL for CloudFront (Note: currently limited to us-east-1).
• MCP Server Stack: Deploys the core compute (ECS Fargate or Lambda), the Application Load Balancer (ALB), and the CloudFront distribution.
• Cross-Region Sync: Ensures WAF parameters are synchronized across regions if necessary.

The implementation uses StreamableHTTP transport for MCP communication, which follows these patterns:

• Protocol: HTTP/HTTPS using JSON-RPC 2.0 over POST requests.
• Statelessness: Each request is treated as a new instance to support concurrent client access.
• Authentication: Every request must include a Bearer token for validation.
• Primary Endpoints:
  • POST /mcp: The main endpoint for MCP tool calls and resource requests.
  • GET /.well-known/oauth-protected-resource: The endpoint for OAuth discovery.

To support standards-compliant authentication, MCP servers should implement the OAuth 2.0 Protected Resource Metadata specification (RFC9728). This allows clients to discover how to authenticate against the resource.

Key Requirements:

• Metadata Endpoint: The server must expose a GET endpoint at /.well-known/oauth-protected-resource.
• Purpose: This endpoint advertises the resource identifier and the supported authorization servers (e.g., AWS Cognito).
• Discovery Flow: When a client receives a 401 Unauthorized response, it uses the resource_metadata URL provided in the WWW-Authenticate header to fetch this configuration.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="mcp-server", resource_metadata="https://example.com/.well-known/oauth-protected-resource"

The integration follows a specific sequence to move from an unauthenticated state to a secure MCP session:

1. Trigger: Client sends an MCP request without a token.
2. Challenge: MCP Server returns 401 Unauthorized with a WWW-Authenticate header containing the resource_metadata URL.
3. Discovery: Client fetches metadata from /.well-known/oauth-protected-resource and identifies the Authorization Server (AS).
4. Configuration: Client fetches the AS metadata via /.well-known/openid-configuration.
5. Authorization: Client initiates an OAuth 2.0 Authorization Code flow with PKCE, including the resource parameter.
6. Token Exchange: After user authorization, the client exchanges the code for an access token.
7. Authenticated Request: Client retries the MCP request using the access token as a Bearer token.

Before deploying, ensure your environment meets the following requirements:

Operating System

• Optimized for Amazon Linux 2 AMI.

Required Tools

• AWS CLI (installed and configured)
• Node.js v14 or later
• AWS CDK installed via npm.

AWS CDK Bootstrap If using AWS CDK for the first time in your account, run:

cdk bootstrap

npm install -g aws-cdk
cdk bootstrap

To update only the MCP server component (e.g., after changing server code or configuration) without redeploying the entire infrastructure, use the following commands:

Without domain configuration:

cdk deploy MCP-Server

With domain configuration:

cdk deploy MCP-Server --context cdnCertificateArn=arn:aws:acm:us-east-1:123456789012:certificate/abc123 --context albCertificateArn=arn:aws:acm:us-east-1:123456789012:certificate/abc123 --context customDomain=mcp-server.example.com

To avoid ongoing costs, remove all deployed resources using the CDK CLI.

Primary Cleanup:

cdk destroy --all

Manual Cleanup Steps (if necessary):

• Empty any created S3 buckets.
• Delete the Cognito User Pool if not needed.
• Remove CloudWatch log groups.
• Delete any created secrets in Secrets Manager.

To install the mcp-simple-auth-client example, navigate to the client directory and use uv to synchronize the environment and reinstall dependencies.

cd examples/clients/simple-auth-client
uv sync --reinstall

The client can be started using uv run mcp-simple-auth-client. You can customize the connection behavior using environment variables:

• To connect to a server on a specific port, set MCP_SERVER_PORT.
• To use SSE transport instead of the default, set MCP_TRANSPORT_TYPE=sse.

# Standard run
uv run mcp-simple-auth-client

# Run with custom server port
MCP_SERVER_PORT=3001 uv run mcp-simple-auth-client

# Run using SSE transport
MCP_TRANSPORT_TYPE=sse uv run mcp-simple-auth-client