dil-bbojko/aws-mcp-workshop

Overview

This is a blueprint for creating a simple, secure MCP server on AWS with the following stack:

API Gateway

This component exposes the MCP server to the internet and handles the authorization of API calls.

Lambda

This component works as a serverless MCP server, using the "AWS Lambda Web Adapter" that is an extension of AWS Lambda that allows it to work as a HTTP server.

Cognito

This component is responsible for the issuance and rotation of JWT tokens that allow clients to access the MCP server by authenticating with the API gateway and the Lambda.

Authentication

Authentication of clients to access MCP server functionality is done at two layers: API Gateway and Lambda. These two layers require the same JWT tokens for authentication. Authentication at the API Gateway level was implemented to avoid the overloading of AWS Lambda functions with invalid requests.

Installation

Requirements

To be able to setup your own MCP server using this library, you will need the following software installed:

• Python 3.10
• An AWS account you can access locally and the permissions to deploy the services mentioned in Overview, and also access this AWS account in the AWS console

Installation process

Dependencies

1. If you do not have python 3.10 installed, install it using brew: brew install python@3.10
2. Create a new virtual environment in the repository using python -m venv .venv
3. Activate the new virtual environment using source .venv/bin/activate
4. Install project dependencies using pip install -r requirements.txt

Create MCP server

1. Set a custom Stack prefix and a custom Cognito domain prefix in stack_names.py.
2. From terminal run cd aws-vault exec <aws-account-profile-name> and then cdk deploy (you can use different AWS authentication method as well).
3. After creating the stack, the CDK deploy prints the URL of the API Gateway URL (MCP Server URL) in the terminal. Save this URL as you will need it later. This is the URL of your MCP server.
4. To be able to call the MCP server, you need to:
   1. Retrieve an authorization token from the Cognito AWS service (which handles token issuance and rotation). To get your access token for the MCP server:
      1. First retrieve the Client ID and Client secret from the AWS console Cognito service, in the us-east-1 region from within <stack_prefix>MCPServerWorkshopPool for the <prefix>MCPServerWorkshopClient (found in App clients).
      2. Place these credentials into the auth.py file within this repository, and run using python auth.py. This should print out your access token to the MCP server. Save this token for step 5.
   2. Place the Cognito User pool ID in the environment variables of the Lambda function under the name USER_POOL_ID:
      1. Searching for the MCPServerWorkshopLambda and look for the Lambda that was created with your stack name (prefix + WorhsopMCPServer)
      2. Navigate to Configuration –> Environment variables. Click Edit. Add a new key-value pair using USER_POOL_ID as the key, and your Cognito User pool ID as the value.
      3. This is necessary, so the Lambda function knows where to find the public key for authenticating the user request. Without placing this environment variable, the function (which is running the MCP server) will fail to run.
5. To test the online MCP server, run MCP inspector using npx @modelcontextprotocol/inspector:
   1. Select Streamable HTTP as the transfer protocol.
   2. Paste the URL retrieved from step 3 into the URL field.
   3. Paste the retrieved access token from step 4.2 into the Authentication / Bearer Token field as is.
6. After connecting to the MCP server, you can test how different tools of the MCP server work by:
   1. Clicking on Tools
   2. Clicking on List Tools
   3. Clicking on tool name (e.g. echo_text)
   4. The tool inspector window should appear on the right side with input field(s).
   5. Add values to the input field(s) and click run
   6. The tool should run
   7. You should be able to observe the response by scrolling down in the tool inspector window on the right