Skip to content
Back to search

guidance-for-deploying-model-context-protocol-servers-on-aws

This Guidance demonstrates how to securely run Model Context Protocol (MCP) servers on the AWS Cloud using containerized architecture. It helps organizations implement industry-standard OAuth 2.0 authentication while protecting server deployments with multiple security layers, including content delivery networks and web application firewalls.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/aws-solutions-library-samples--guidance-for-deploying-model-context-protocol-servers-on-aws/badge.svg)](/listings/aws-solutions-library-samples--guidance-for-deploying-model-context-protocol-servers-on-aws)

HTML

<a href="/listings/aws-solutions-library-samples--guidance-for-deploying-model-context-protocol-servers-on-aws"><img src="/api/listings/aws-solutions-library-samples--guidance-for-deploying-model-context-protocol-servers-on-aws/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 327 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Guidance for Deploying Model Context Protocol Servers on AWS
  2. ## Table of Contents
  3. 1. [Overview](#overview)
  4. - [Cost](#cost)
  5. 2. [Prerequisites](#prerequisites)
  6. - [Operating System](#operating-system)
  7. 3. [Deployment Steps](#deployment-steps)
  8. 4. [Deployment Validation](#deployment-validation)
  9. 5. [Running the Guidance](#running-the-guidance)
  10. 6. [Next Steps](#next-steps)
  11. 7. [Cleanup](#cleanup)
  12. 8. [FAQ, known issues, additional considerations, and limitations](#faq-known-issues-additional-considerations-and-limitations)
  13. 9. [Revisions](#revisions)
  14. 10. [Notices](#notices)
  15. ## Overview
  16. This guidance demonstrates how to deploy Model Context Protocol (MCP) servers on AWS with secure authentication using Amazon Cognito, implementing the **2025-06-18 MCP specification** with OAuth 2.0 Protected Resource Metadata (RFC9728). It enables you to host MCP servers that can be accessed remotely while maintaining security through standards-compliant OAuth 2.0 authentication flows.
  17. The solution addresses several key challenges:
  18. - Secure hosting of MCP servers on AWS infrastructure
  19. - Standards-compliant authentication using OAuth 2.0 Protected Resource Metadata (RFC9728)
  20. - Remote access to MCP servers through secure StreamableHTTP transport
  21. - Stateless server architecture for concurrent client support
  22. - Scalable and maintainable deployment using AWS CDK
  23. ### Architecture
  24. ![Architecture Diagram](assets/architecture-diagram.png)
  25. The architecture implements:
  26. 1. **CloudFront distribution** for global content delivery with WAF protection
  27. 2. **Application Load Balancer** for traffic distribution and SSL termination
  28. 3. **ECS Fargate and Lambda** for containerized and serverless MCP servers
  29. 4. **AWS Cognito** for OAuth 2.0 authorization server functionality
  30. 5. **OAuth 2.0 Protected Resource Metadata** endpoints for standards-compliant authentication
  31. 6. **StreamableHTTP transport** with stateless request handling
  32. 7. **Four-stack CDK deployment**: VPC, Security, CloudFront WAF, and MCP Server stacks
  33. ### Cost
  34. You are responsible for the cost of the AWS services used while running this Guidance. As of August 2025, the cost for running this Guidance with the default settings in the US East (N. Virginia) Region is approximately $194.18 per month for processing moderate traffic levels.
  35. We recommend creating a [Budget](https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html) through [AWS Cost Explorer](https://aws.amazon.com/aws-cost-management/aws-cost-explorer/) to help manage costs. Prices are subject to change. For full details, refer to the pricing webpage for each AWS service used in this Guidance.
  36. #### Estimated Cost Table
  37. The following table provides a sample cost breakdown for deploying this Guidance with the default parameters in the US East (N. Virginia) Region for one month.
  38. | AWS service | Dimensions | Cost [USD] |
  39. | ---------------------- | -------------------------------------------------- | ----------------- |
  40. | VPC (NAT Gateway) | 1 NAT Gateway × 730 hours + 100 GB data processing | $37.35 |
  41. | Elastic Load Balancing | Application Load Balancer with moderate traffic | $16.83 |
  42. | Amazon Cognito | 10,500 MAUs (within 50,000 free tier) | $0.00 |
  43. | CloudFront | 2 TB data transfer + 15M requests | $87.96 |
  44. | WAF | 2 Web ACLs (CloudFront and Regional) | $10.00 |
  45. | ECS (Fargate) | 1 vCPU, 2GB memory × 730 hours | $36.04 |
  46. | Secrets Manager | 1 secret for Cognito credentials | $0.40 |
  47. | Lambda | Custom resources (minimal usage) | $0.20 |
  48. | **Total** | | **$194.18/month** |
  49. ## Prerequisites
  50. ### Operating System
  51. These deployment instructions are optimized to work on **Amazon Linux 2 AMI**. Deployment in another OS may require additional steps.
  52. ### Required Tools
  53. 1. [AWS CLI](https://aws.amazon.com/cli/) installed and configured
  54. 2. [Node.js](https://nodejs.org/) v14 or later
  55. 3. [AWS CDK](https://aws.amazon.com/cdk/) installed:
  56. ```bash
  57. npm install -g aws-cdk
  58. ```
  59. ### AWS CDK Bootstrap
  60. If you're using AWS CDK for the first time, bootstrap your account:
  61. ```bash
  62. cdk bootstrap
  63. ```
  64. ## Deployment Steps
  65. 1. Clone the repository:
  66. ```bash
  67. git clone <repository-url>
  68. cd guidance-for-deploying-model-context-protocol-servers-on-aws
  69. cd source/cdk/ecs-and-lambda
  70. ```
  71. 2. Install dependencies:
  72. ```bash
  73. npm install
  74. ```
  75. 3. Login to public ECR:
  76. ```bash
  77. aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws
  78. ```
  79. 4. Deploy the stacks:
  80. Without domain configuration:
  81. ```bash
  82. cdk deploy --all
  83. ```
  84. Or with domain configuration (single region - us-east-1):
  85. ```bash
  86. cdk deploy --all --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
  87. ```
  88. Or with multi-region certificate configuration:
  89. ```bash
  90. cdk deploy --all --context cdnCertificateArn=arn:aws:acm:us-east-1:123456789012:certificate/abc123 --context albCertificateArn=arn:aws:acm:eu-west-1:123456789012:certificate/def456 --context customDomain=mcp-server.example.com
  91. ```
  92. Or with CloudFront HTTPS only (ALB stays HTTP):
  93. ```bash
  94. cdk deploy --all --context cdnCertificateArn=arn:aws:acm:us-east-1:123456789012:certificate/abc123 --context customDomain=mcp-server.example.com
  95. ```
  96. 5. Update MCP servers:
  97. Without domain configuration:
  98. ```bash
  99. cdk deploy MCP-Server
  100. ```
  101. Or with domain configuration:
  102. ```bash
  103. 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
  104. ```
  105. ## Deployment Validation
  106. 1. Verify CloudFormation stack status:
  107. - Open AWS CloudFormation console
  108. - Check that all stacks show "CREATE_COMPLETE"
  109. 2. Validate Cognito setup:
  110. - Open Amazon Cognito console
  111. - Verify User Pool creation
  112. - Confirm App Client configuration
  113. 3. Verify infrastructure:
  114. - CloudFront distribution is "Deployed"
  115. - Application Load Balancer is "Active"
  116. - ECS services are running
  117. ## Running the Guidance
  118. ### Testing with Cognito Users (Development Only)
  119. For development and testing environments only, you can quickly create and manage users with AWS CLI:
  120. ```bash
  121. # Create test user
  122. aws cognito-idp admin-create-user --user-pool-id YOUR_USER_POOL_ID --username test@example.com
  123. # Set permanent password (bypass temporary)
  124. aws cognito-idp admin-set-user-password --user-pool-id YOUR_USER_POOL_ID --username test@example.com --password "TestPass123!" --permanent
  125. ```
  126. ### Testing with the Sample Python MCP Client
  127. The deployment includes a sample Python MCP client that demonstrates OAuth 2.0 Protected Resource authentication with the deployed servers. This client implements the 2025-06-18 MCP specification with StreamableHTTP transport.
  128. > **Note:** This client is a modified version of the [simple-auth-client example](https://github.com/modelcontextprotocol/python-sdk/tree/main/examples/clients/simple-auth-client) from the official MCP Python SDK.
  129. ### Why Use the Python Client?
  130. The included Python client (`source/sample-clients/simple-auth-client-python/`) demonstrates:
  131. - **OAuth 2.0 Protected Resource Metadata** (RFC9728) authentication flow
  132. - **StreamableHTTP transport** communication
  133. - **Interactive CLI interface** for testing MCP tools
  134. - **Standards-compliant implementation** of the 2025-06-18 MCP specification
  135. > **Important:** This implementation does **not support Dynamic Client Registration (DCR)**. Client credentials must be pre-configured in AWS Cognito and provided via environment variables.
  136. ### Using the Python Client
  137. 1. Navigate to the client directory:
  138. ```bash
  139. cd source/sample-clients/simple-auth-client-python
  140. ```
  141. 2. Install dependencies with uv:
  142. ```bash
  143. pip install uv
  144. uv sync --reinstall
  145. ```
  146. 3. Set environment variables:
  147. ```bash
  148. export MCP_SERVER_URL="https://<your-cloudfront-endpoint>/weather-nodejs/mcp"
  149. export OAUTH_CLIENT_ID="<your-cognito-client-id>"
  150. export OAUTH_CLIENT_SECRET="<your-cognito-client-secret>"
  151. ```
  152. 4. Run the client:
  153. ```bash
  154. uv run python -m mcp_simple_auth_client.main
  155. ```
  156. 5. Test available endpoints:
  157. - **ECS Fargate Server**: `https://<your-cloudfront-endpoint>/weather-nodejs/mcp`
  158. - **Lambda Server**: `https://<your-cloudfront-endpoint>/weather-nodejs-lambda/mcp`
  159. The client will automatically handle the OAuth flow, open a browser for authentication, and provide an interactive CLI to test the MCP tools.
  160. ## Next Steps
  161. 1. Implement additional MCP servers:
  162. - Add new server containers to ECS
  163. - Configure OAuth flows for new servers
  164. - Update client configurations for new endpoints
  165. 2. Optimize costs:
  166. - Monitor usage patterns
  167. - Consider reserved capacity for steady workloads
  168. - Implement caching strategies
  169. 3. Enhance security:
  170. - Enable MFA in Cognito
  171. - Implement additional WAF rules
  172. - Set up monitoring and alerting
  173. ## Cleanup
  174. 1. Remove deployed resources:
  175. ```bash
  176. cdk destroy --all
  177. ```
  178. 2. Manual cleanup steps:
  179. - Empty any created S3 buckets
  180. - Delete Cognito User Pool (if not needed)
  181. - Remove CloudWatch log groups
  182. - Delete any created secrets in Secrets Manager
  183. ## FAQ, known issues, additional considerations, and limitations
  184. ### Known Issues
  185. 1. Token refresh may require re-authentication in some cases
  186. 2. CloudFront cache invalidation may take up to 5 minutes
  187. 3. Initial cold start delay for Fargate containers
  188. ### Additional Considerations
  189. - **OAuth 2.0 Compliant**: Implements RFC9728 Protected Resource Metadata specification
  190. - **Stateless Architecture**: Each request creates new server instance for concurrent client support
  191. - **Public endpoints are created** for OAuth Protected Resource Metadata discovery
  192. - **CloudFront distributions** may take 15-20 minutes to deploy
  193. - **Four-stack deployment**: VPC, Security, CloudFront WAF, and MCP Server stacks
  194. For detailed information, refer to these additional documentation files:
  195. - [Monthly Cost Estimate Report](assets/cost-estimate-report.md)
  196. - [AWS Architecture & OAuth 2.0 Flow](assets/aws-cognito-mcp-integration.md)
  197. ### Limitations
  198. 1. **No Dynamic Client Registration (DCR)**: Client credentials must be pre-configured in AWS Cognito
  199. 2. **Region availability** depends on AWS Cognito support
  200. 3. **Multi-region certificate requirements**:
  201. - CloudFront certificates (`cdnCertificateArn`) must be in us-east-1
  202. - ALB certificates (`albCertificateArn`) must be in the deployment region
  203. - Both certificates must cover the same custom domain
  204. 4. **CloudFront WAF only**: AWS WAF is configured for CloudFront distribution, not ALB directly
  205. 5. **StreamableHTTP transport only**: SSE transport (deprecated) not supported in this implementation
  206. 6. **Some MCP clients** may not support remote connections or OAuth flows
  207. For any feedback, questions, or suggestions, please use the issues tab under this repo.
  208. ## Revisions
  209. ### [2.0.0] - 2025-08-25
  210. - **BREAKING CHANGE**: Migrate to 2025-06-18 MCP specification
  211. - Implement OAuth 2.0 Protected Resource Metadata (RFC9728)
  212. - Replace SSE transport with StreamableHTTP transport
  213. - Add stateless server architecture for concurrent client support
  214. - Remove Dynamic Client Registration (DCR) - clients must be pre-configured
  215. - Restructure project to `source/cdk/ecs-and-lambda/` for better organization
  216. - Add sample Python MCP client with interactive CLI
  217. - Implement four-stack CDK deployment (VPC, Security, CloudFront WAF, MCP Server)
  218. - Add Lambda-based MCP server deployment option
  219. - Remove DynamoDB token storage - now using stateless authentication
  220. ### [1.0.0] - 2025-05-06
  221. - Initial release
  222. - Basic OAuth flow implementation
  223. - Support for weather sample servers
  224. ## Notices
  225. Customers are responsible for making their own independent assessment of the information in this Guidance. This Guidance: (a) is for informational purposes only, (b) represents AWS current product offerings and practices, which are subject to change without notice, and (c) does not create any commitments or assurances from AWS and its affiliates, suppliers or licensors. AWS products or services are provided "as is" without warranties, representations, or conditions of any kind, whether express or implied. AWS responsibilities and liabilities to its customers are controlled by AWS agreements, and this Guidance is not part of, nor does it modify, any agreement between AWS and its customers.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.