serverless

This MCP server demonstrates a stateless implementation of the Model Context Protocol (MCP) running on AWS Lambda and API Gateway using the Streamable HTTP transport. It can be deployed and managed via CDK and GitHub Actions, with the Lambda/API Gateway stack exposing an MCP endpoint once deployed. Locally, you can run the MCP server and a client to exercise the tools and interactions defined by the MCP transport, then deploy to AWS to make the endpoint available to your clients. The provided client script can query available tools (for example, a ping tool) and invoke MCP tools through the endpoint.

To use the server, install dependencies, run the local server, and (optionally) run the client to exercise MCP tooling. When deployed, the CDK-based workflow provisions separate stacks for dev, qas, and prod environments and prints the endpoint URL for use by the client. The client can issue tool calls and observe responses via the MCP transport over HTTP(S) endpoints generated by API Gateway.

Prerequisites:

• AWS CLI configured with credentials
• Node.js 20+
• Yarn

1. Clone the project and install dependencies

git clone <your-repo-url>
cd serverless-mcp

Install all dependencies (authorizer, mcpserver, and CDK):

yarn installall

Alternatively install per-package:

(cd src/authorizer && yarn install)
(cd src/mcpserver && yarn install)
(cd cdk && yarn install)

2. Run locally (for testing the MCP server and client locally)

node src/mcpserver/index.js

In a separate terminal, run the client:

node src/mcpclient/index.js

3. Deploy to AWS with CDK

From repo root:

yarn installall
yarn buildall
yarn deploy

By default this deploys the dev stack (mcp-dev-stack). To target other stages/regions:

STAGE=qas REGION=ap-southeast-2 yarn deploy

Or run from the CDK package:

(cd cdk && yarn deploy)

After deployment, the CDK output will include the MCP endpoint. Export it for the client:

export MCP_SERVER_ENDPOINT=<value from McpEndpoint output>

Note: It may take about a minute for the API Gateway endpoint to become available.

4. Test the remote MCP server with the client

node src/mcpclient/index.js

The client will connect to the deployed endpoint and perform tool discovery and calls. The endpoint URL will match your deployment (e.g., https://<api-id>.execute-api.<region>.amazonaws.com/<stage>/mcp).

Tips and common issues:

• Stateless mode means the MCP server does not keep persistent SSE connections. This supports horizontal scaling but may affect how clients receive notifications.
• Ensure AWS permissions are in place for CDK deployments (CloudFormation, Lambda, API Gateway, IAM, and S3 for assets).
• Remember to destroy the stack when you’re done testing to avoid ongoing costs: cd cdk yarn destroy
• The deployment workflow relies on secrets like AWS credentials and a management API key. Configure them per environment (dev, qas, prod) in GitHub Settings → Environments.
• If you modify authorization, update src/mcpclient/index.js to include any required Authorization header (e.g., Bearer token) when calling the MCP endpoint.