# Terraform Quick Start Guide
Deploy the MCP Gateway to AWS using Terraform in minutes!
## Prerequisites Check
```bash
# Check Terraform version (need 1.0+)
terraform --version
# Check AWS CLI
aws --version
# Verify AWS credentials
aws sts get-caller-identity
```
## Quick Start Steps
### 1. Configure Variables
```bash
cd terraform
cp terraform.tfvars.example terraform.tfvars
```
Edit `terraform.tfvars` with your settings:
```hcl
aws_region = "us-east-1"
environment = "dev"
log_retention_days = 7
# Python Dependencies Lambda Layer (Required)
# This layer contains all Python dependencies from requirements.txt
# Create using: ./create_dependencies_layer.sh 3.11 mcp-dependencies-python311 us-east-1 ../requirements.txt
python_dependencies_layer_arn = ""
tags = {
Project = "mcp-gateway"
ManagedBy = "terraform"
}
```
### 2. Initialize Terraform
```bash
terraform init
```
This downloads the AWS provider and initializes the backend.
### 3. Review Deployment Plan
```bash
terraform plan
```
This shows you what resources will be created:
- 5 Lambda functions (Gateway + 3 tool functions + REST API server)
- 2 IAM roles with policies
- 2 API Gateway REST APIs (MCP Gateway + REST API Server)
- 5 CloudWatch Log Groups
### 4. Deploy to AWS
```bash
terraform apply
```
Type `yes` when prompted to confirm deployment.
### 5. Get Your Gateway URL
```bash
terraform output mcp_gateway_api_url
```
Copy the URL - you'll need it to test the gateway!
## What Gets Deployed
✅ **Lambda Functions**:
- `{env}-mcp-gateway` - Main MCP protocol handler
- `{env}-weather-tool` - Weather lookup tool
- `{env}-calculator-tool` - Calculator tool
- `{env}-data-lookup-tool` - Data lookup tool
- `{env}-rest-api-server` - REST API server (FastAPI with Mangum)
✅ **API Gateways**:
- MCP Gateway API - REST API endpoint at `/mcp` for MCP protocol requests
- REST API Server - FastAPI endpoints for REST tools (stock_price, current_time, summarize_text)
✅ **IAM Roles**:
- Gateway role (can invoke tool Lambdas)
- Tool role (basic Lambda execution)
✅ **CloudWatch Logs**:
- Log groups for each Lambda function
## Python Dependencies Layer
The configuration uses a comprehensive Python dependencies Lambda layer that contains all required packages from `requirements.txt`.
### Creating the Layer
The layer must be built using Docker to ensure all compiled extensions (like `pydantic_core`) are built for the correct architecture (Linux x86_64):
```bash
cd terraform
./create_dependencies_layer.sh 3.11 mcp-dependencies-python311 us-east-1 ../requirements.txt
```
This script:
- Uses Docker to build for Linux x86_64 (Lambda's architecture)
- Installs all dependencies from `requirements.txt` (excluding boto3, botocore, pytest*)
- Verifies compiled extensions are for the correct architecture
- Creates and publishes the layer to AWS
### Using the Layer
1. **Create the layer** using the script above
2. **Set the layer ARN** in `terraform.tfvars`:
```hcl
python_dependencies_layer_arn = "arn:aws:lambda:us-east-1:YOUR_ACCOUNT:layer:mcp-dependencies-python311:1"
```
3. **Deploy**:
```bash
terraform apply
```
The layer is automatically attached to Lambda functions that need dependencies (MCP Gateway and REST API Server).
### Benefits
- **All dependencies in one layer**: Easier to manage and update
- **Faster deployments**: Layer cached, only code changes trigger updates
- **Correct architecture**: Built for Linux x86_64 using Docker
- **Package metadata preserved**: Includes .dist-info for proper Python imports
## Testing Your Deployment
### Test the Gateway
```bash
# Get the API Gateway URL
GATEWAY_URL=$(terraform output -raw mcp_gateway_api_url)
# List available tools
curl -X POST $GATEWAY_URL/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list",
"params": {}
}'
# Call the weather tool
curl -X POST $GATEWAY_URL/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "weather_lookup",
"arguments": {
"location": "New York, NY",
"units": "celsius"
}
}
}'
# Call the calculator tool
curl -X POST $GATEWAY_URL/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "calculator",
"arguments": {
"operation": "add",
"a": 10,
"b": 5
}
}
}'
```
### View Logs
```bash
# View gateway logs
aws logs tail /aws/lambda/dev-mcp-gateway --follow
# View tool logs
aws logs tail /aws/lambda/dev-weather-tool --follow
```
## Common Operations
### Update Lambda Code
```bash
# Make changes to your Lambda functions
# Then apply changes
terraform apply
```
### Add a New Tool
1. Create your Lambda function file in `tools/lambda_functions/`
2. Add archive data source in `main.tf`
3. Add Lambda function resource in `main.tf`
4. Update IAM policy to allow invocation
5. Run `terraform apply`
### Change Layer Version
```bash
# Rebuild the layer (creates new version)
./create_dependencies_layer.sh 3.11 mcp-dependencies-python311 us-east-1 ../requirements.txt
# Update terraform.tfvars with new layer ARN
python_dependencies_layer_arn = "arn:aws:lambda:us-east-1:YOUR_ACCOUNT:layer:mcp-dependencies-python311:5"
# Apply changes
terraform apply
```
## Outputs
Get useful information after deployment:
```bash
# API Gateway URLs
terraform output mcp_gateway_api_url
terraform output rest_api_server_url
# Lambda function ARNs
terraform output mcp_gateway_function_arn
terraform output weather_tool_function_arn
terraform output calculator_tool_function_arn
terraform output data_lookup_tool_function_arn
terraform output rest_api_server_function_arn
# All outputs
terraform output
```
## Cleanup
To remove all resources:
```bash
terraform destroy
```
Type `yes` when prompted. This will delete:
- All Lambda functions
- API Gateway
- IAM roles and policies
- CloudWatch Log Groups
## Troubleshooting
### Terraform Init Fails
```bash
# Check AWS credentials
aws sts get-caller-identity
# Verify Terraform version
terraform --version
```
### Lambda Function Errors
```bash
# Check CloudWatch logs
aws logs tail /aws/lambda/dev-mcp-gateway --follow
# Verify IAM permissions
terraform show | grep aws_iam_role
```
### API Gateway 500 Errors
```bash
# Check Lambda function logs
aws logs tail /aws/lambda/dev-mcp-gateway --follow
# Verify Lambda permission for API Gateway
terraform show | grep aws_lambda_permission
```
### Layer Issues
**Layer Not Found:**
- Verify the layer ARN is correct for your region
- Check that the Python runtime matches the layer version
- Ensure the layer exists in your AWS account/region
**Import Errors (pydantic_core, email-validator, etc.):**
- Layer was built for wrong architecture (ARM64 instead of x86_64)
- Solution: Rebuild layer using Docker: `./create_dependencies_layer.sh 3.11 mcp-dependencies-python311 us-east-1 ../requirements.txt`
- Verify layer has x86_64 compiled extensions: `./test_layer.sh mcp-dependencies-python311 VERSION us-east-1`
- Ensure `.dist-info` directories are not removed (they contain package metadata)
### State Lock Issues
```bash
# If Terraform state is locked
terraform force-unlock <LOCK_ID>
```
## Next Steps
1. **Customize Tools**: Add your own Lambda functions
2. **Add Authentication**: Configure API Gateway authorizers
3. **Set Up Monitoring**: Create CloudWatch dashboards
4. **Production Deployment**: Use remote state backend (S3)
5. **Multi-Environment**: Create separate workspaces for dev/staging/prod
## Using Makefile (Optional)
The `terraform/Makefile` provides convenient shortcuts:
```bash
# Initialize
make init
# Plan
make plan
# Apply
make apply
# Destroy
make destroy
# Outputs
make output
```
## Comparison: Terraform vs SAM
| Feature | Terraform | SAM |
|---------|-----------|-----|
| **State Management** | Terraform state | CloudFormation |
| **Language** | HCL | YAML |
| **Lambda Layers** | Explicit configuration | Automatic detection |
| **Dependencies** | Manual layer creation (Docker) | Automatic packaging |
| **Flexibility** | High | Medium |
| **Learning Curve** | Steeper | Gentler |
| **Best For** | Complex infrastructure, production | Simple serverless apps |
## Learn More
- See `terraform/README.md` for detailed Terraform guide
- See `DEPLOYMENT.md` for SAM deployment option
- See `README.md` for project overview
- See `QUICKSTART.md` for local development
## Support
For issues:
1. Check CloudWatch logs
2. Run `terraform plan` to verify configuration
3. Review `terraform/README.md` for detailed troubleshooting
