MCP Server for AWS AppRunner
A boilerplate Model Context Protocol (MCP) server implementation using TypeScript, Express.js, and the @modelcontextprotocol/sdk. This server is designed to be deployed to AWS AppRunner.
Overview
This server implements the Model Context Protocol, enabling AI assistants and applications to securely connect to external tools, data sources, and resources. The server provides:
- Tool Integration: Define and expose tools that AI can use to perform actions 
- Resource Access: Control access to files and other resources 
- Prompt Templates: Provide standardized prompt templates for consistent interactions 
Features
- MCP Server implementation with TypeScript and Express.js 
- Streamable HTTP transport supporting both JSON-RPC and SSE 
- Sample tools, resources, and prompts 
- AWS AppRunner deployment configuration 
- Docker containerization with production and development configurations 
- Docker Compose for local development with hot reloading 
- GitHub Actions CI/CD workflow 
- Environment configuration management 
- Structured logging with Pino 
- MCP Inspector integration for testing and debugging 
Requirements
- Node.js 20+ 
- npm or yarn 
- Docker (for containerization) 
- Docker Compose (for local development) 
- AWS account (for deployment) 
Getting Started
Installation
- Clone this repository: git clone https://github.com/yourusername/mcp-server.git cd mcp-server
- Install dependencies: npm install
- Create a - .envfile based on the example:cp .env.example .env
Development
Local Development
- Start the development server: npm run dev
- The server will be available at http://localhost:3000 
Docker Compose Development (Recommended)
This method provides a consistent development environment with hot reloading:
- Optional: Configure npm registry for development: - The project is configured to work with both public and private npm registries: - Using public registry (default): No action needed. 
- Using private/corporate registry: Create a - .npmrcfile in the project root with your registry configuration:registry=https://your-private-registry.com/ strict-ssl=true|false
 
- Start the Docker development environment: docker-compose up -d
- View logs in real-time: docker-compose logs -f
- The server will be available at http://localhost:3000 
- Changes to source files will be automatically reflected in the running container thanks to volume mounts and hot reloading 
- Stop the development container: docker-compose down
Using the Makefile
This project includes a Makefile to simplify common development tasks:
- Start the MCP server with Docker Compose: make mcp
- Start the MCP Inspector for testing and debugging: make inspector
- Start both the MCP server and Inspector together: make start
- Start both services using Docker Compose: make compose
- Stop all running containers: make stop
- Clean up containers and images: make clean
Using the MCP Inspector
The MCP Inspector is a tool for testing and debugging MCP implementations:
- Start the Inspector using one of these methods: # Stand-alone Inspector make inspector # Both MCP server and Inspector with Docker Compose make compose
- Access the Inspector web UI at http://localhost:6274 
- Connect to your local MCP server at http://localhost:3000 
- Use the Inspector to: - Test MCP initialization and session management 
- Discover available tools, resources, and prompts 
- Make tool calls and view responses 
- Debug protocol communication issues 
 
Testing Your MCP Server
You can test the MCP server using cURL:
Project Structure
Docker Configuration
The project includes two Docker configurations:
Development Docker (Dockerfile.dev)
- Based on Node.js 20 Alpine 
- Supports both public and private npm registries 
- Mounts source code for hot reloading 
- Uses tsx for TypeScript execution without compilation 
- Configured to work with or without an - .npmrcfile
Production Docker (Dockerfile)
- Multi-stage build for optimized image size 
- First stage builds the TypeScript application 
- Second stage contains only the compiled JavaScript and production dependencies 
- Uses public npm registry for AWS AppRunner deployment 
- Optimized for security and performance 
Deployment to AWS AppRunner
Prerequisites
- AWS account with appropriate permissions 
- AWS CLI configured 
- ECR repository created for the container image 
- AppRunner service role with permissions to pull from ECR 
Manual Deployment
- Build and tag the Docker image: docker build -t your-ecr-repo/mcp-server:latest .
- Push the image to ECR: aws ecr get-login-password --region your-region | docker login --username AWS --password-stdin your-account-id.dkr.ecr.your-region.amazonaws.com docker push your-ecr-repo/mcp-server:latest
- Create or update the AppRunner service: aws apprunner create-service --cli-input-json file://apprunner-config.json
GitHub Actions Deployment
This repository includes a GitHub Actions workflow in .github/workflows/deploy.yml that automates the deployment process when you push to the main branch.
To use it, set up the following GitHub secrets:
- AWS_ACCESS_KEY_ID: AWS access key with appropriate permissions
- AWS_SECRET_ACCESS_KEY: AWS secret access key
- AWS_REGION: AWS region for deployment
- ECR_REPOSITORY: Name of your ECR repository
- APPRUNNER_SERVICE: Name of your AppRunner service
- APPRUNNER_SERVICE_ROLE_ARN: ARN of the service role for AppRunner
Customization
Adding New Tools
Edit src/mcp/tools.ts to add new tool definitions and handlers:
Adding New Resources
Edit src/mcp/resources.ts to add new resource definitions and content.
Adding New Prompts
Edit src/mcp/prompts.ts to add new prompt templates.
License
MIT
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
A boilerplate TypeScript MCP server with Express.js designed for AWS AppRunner deployment. Provides sample tools, resources, and prompts with Docker containerization and GitHub Actions CI/CD workflow.