TypeScript MCP Server Starter

A production-ready TypeScript MCP server template using HTTP transport with API key authentication, structured logging, health monitoring, and Docker support.

Overview

This template gives you a solid foundation for building Model Context Protocol (MCP) servers in TypeScript. It uses HTTP transport so your server can be deployed as a standard web service and called by any MCP-compatible client including Claude Desktop, Cursor, and Windsurf. Authentication is handled via API keys passed in request headers, making it straightforward to secure your server without complex OAuth flows.

The template is designed for developers who are new to MCP but comfortable with TypeScript and Node.js. Every piece of the stack — logging, configuration, authentication, health checks, and testing — is wired up and working out of the box. You clone the repo, set your environment variables, run docker compose up, and you have a running MCP server ready to extend with your own tools.

Inside you will find three realistic tool implementations: a text analysis tool that counts words, sentences, and estimates reading time; a URL metadata fetcher that retrieves page titles and descriptions; and a Markdown-to-plain-text converter. These serve as practical examples of how to validate inputs, handle errors gracefully, and return well-structured responses — patterns you will apply directly to your own domain-specific tools.

What You'll Learn

• How to structure a TypeScript MCP server project for maintainability and growth
• Registering tools with the MCP SDK including input schemas and typed handlers
• Implementing API key authentication as Express middleware
• Loading and validating configuration from environment variables with Zod
• Setting up Pino for structured JSON logging with request correlation IDs
• Building a /health endpoint that returns dependency status as structured JSON
• Writing unit and integration tests for MCP tools using Jest and Supertest
• Containerising a Node.js service with a multi-stage Dockerfile and Docker Compose

Architecture

HTTP Client / MCP Host
        │
        ▼
  Express Server
  ├── POST /mcp        ← MCP tool calls (requires X-API-Key header)
  ├── GET  /mcp        ← SSE stream for server-sent events
  ├── DELETE /mcp      ← Session teardown
  └── GET  /health     ← Dependency & liveness check (no auth)
        │
        ▼
  McpServer (SDK)
  ├── analyzeText      ← Word / sentence / reading-time stats
  ├── fetchUrlMetadata ← Page title + description via HTTP
  └── markdownToText   ← Strip Markdown → plain text

Requests arrive at Express. The requireApiKey middleware rejects any request to /mcp that is missing or has an incorrect X-API-Key header. Valid requests are forwarded to a StreamableHTTPServerTransport instance which handles the MCP wire protocol and dispatches to the registered tool handlers.

Project Structure

.
├── src/
│   ├── __tests__/
│   │   ├── setup.ts          # Jest global env setup
│   │   ├── health.test.ts    # Health endpoint tests
│   │   └── server.test.ts    # Auth + MCP protocol tests
│   ├── tools/
│   │   ├── analyzeText.ts    # Text statistics tool
│   │   ├── fetchUrlMetadata.ts # URL metadata tool
│   │   └── markdownToText.ts # Markdown converter tool
│   ├── auth.ts               # API key middleware
│   ├── config.ts             # Zod-validated env config
│   ├── health.ts             # Health check handler
│   ├── logger.ts             # Pino logger setup
│   └── server.ts             # Express app + MCP wiring
├── .env.example              # Environment variable documentation
├── Dockerfile                # Multi-stage production image
├── docker-compose.yml        # Local / CI compose file
├── jest.config.ts            # Jest configuration
├── package.json
└── tsconfig.json

Prerequisites

• Node.js 20+ — required by the engines field in package.json
• npm 10+ — ships with Node.js 20
• Docker + Docker Compose — for the containerised workflow (optional)
• Basic familiarity with TypeScript and Express

Quick Start

Local development

# 1. Clone and install
git clone <your-repo-url>
cd typescript-mcp-starter
npm install

# 2. Configure environment
cp .env.example .env
# Edit .env and set MCP_API_KEY to a strong random value:
# openssl rand -hex 32

# 3. Start the dev server (hot-reload)
npm run dev

# 4. Verify health
curl http://localhost:3000/health

# 5. Call a tool
curl -X POST http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: <your-key>' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Docker

cp .env.example .env   # fill in MCP_API_KEY
docker compose up --build

Features

Works With

• Claude Desktop — add the server URL and API key to claude_desktop_config.json
• Cursor — configure under Settings → MCP Servers
• Windsurf — add to your MCP configuration file
• Any MCP-compatible client that supports HTTP transport

Claude Desktop configuration example

{
  "mcpServers": {
    "my-server": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "X-API-Key": "your-api-key-here"
      }
    }
  }
}

Configuration

All configuration is read from environment variables. Copy .env.example to .env and adjust as needed.

Generate a strong API key:

openssl rand -hex 32

Deployment

Railway / Render / Fly.io

1. Push your repo to GitHub.
2. Create a new service pointing at the repo.
3. Set the environment variables listed above in the platform's dashboard.
4. The platform will detect the Dockerfile and build automatically.

Manual VPS

# Build the production image
docker build -t mcp-server .

# Run with env vars from a .env file
docker run -d \
  --name mcp-server \
  -p 3000:3000 \
  --env-file .env \
  --restart unless-stopped \
  mcp-server

Production Checklist

• MCP_API_KEY is set to a cryptographically random value of ≥ 32 characters
• NODE_ENV=production is set (enables JSON logging)
• LOG_LEVEL=info or higher (avoid debug/trace in prod)
• Server is behind a TLS-terminating reverse proxy (nginx, Caddy, ALB, etc.)
• Health endpoint is wired to your load balancer / container orchestrator
• Docker image is built from the runner stage (not builder)
• Container runs as the node user (non-root)
• .env is in .gitignore and never committed
• Dependency audit: npm audit --omit=dev

Testing

# Run all tests
npm test

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

The test suite covers:

• health.test.ts — GET /health shape, timestamp validity, no-auth access, uptime format
• server.test.ts — authentication (missing key, wrong key, valid key), tools/list response shape, tool call happy-paths and error cases

Tests use a shared setup.ts that injects safe test values for all required environment variables before any module is imported.