agent-mcp-tools-1

A production-leaning MCP server starter for AWS Lambda. It follows the shape of aal80/peppa-mcp-server-on-lambda but uses maintained, widely adopted building blocks:

• Official Model Context Protocol TypeScript SDK (@modelcontextprotocol/sdk)
• Streamable HTTP transport, the current MCP remote-server transport
• Express 5 for local HTTP routing
• Zod for tool input validation
• AWS Lambda Web Adapter for running the same HTTP app locally, in Docker, or on Lambda
• Terraform for AWS Lambda + API Gateway HTTP API infrastructure
• Vitest, TypeScript, ESLint, and Prettier for day-to-day engineering hygiene

The sample MCP surface mirrors the Peppa-style flow:

• Resource: tickets://timeslots
• Tool: order_tickets

Local Development

npm install
npm run dev

In another terminal:

npm run client

Or inspect it with the MCP Inspector:

npm run inspect

Stdio Mode

Some local MCP clients prefer stdio:

npm run stdio

Verify

npm run typecheck
npm test
npm run lint
npm run build

Docker

docker build -t agent-mcp-tools-1:local .
docker run --rm -p 8080:8080 \
  -e HOST=0.0.0.0 \
  -e MCP_ALLOWED_ORIGINS=http://127.0.0.1:6274,http://localhost:6274 \
  agent-mcp-tools-1:local

AWS Deploy

Build and push the container image to ECR, then pass the ECR image URI to Terraform:

cd terraform
terraform init
terraform apply -var "image_uri=<account>.dkr.ecr.<region>.amazonaws.com/agent-mcp-tools-1:latest"

Terraform outputs endpoint_url, which is the MCP Streamable HTTP endpoint.

Security Notes

MCP's Streamable HTTP specification calls out origin validation, localhost-only binding for local servers, and authentication for remote deployments. This starter implements origin validation and localhost binding by default. Add your preferred auth layer before exposing a real production tool publicly.

Replacing The Sample Tool

Keep the transport and deployment code as-is, then replace:

• src/domain/tickets.ts
• the resource/tool registrations in src/mcp/server.ts
• the smoke client arguments in src/client.ts