Production-Ready MCP Server Boilerplate

Ship reliable MCP servers in minutes, not days. A production-ready foundation for building Model Context Protocol servers with built-in security, authentication, and observability.

[!NOTE] This is a starter template — not a finished product. You are responsible for reviewing and securing any code before production use.

![TypeScript](https://www.typescriptlang.org/) ![License: MIT](LICENSE) ![MCP Compliant](https://modelcontextprotocol.io/)

Don't build from scratch. This kit solves the "boring" parts of MCP server development—transport management, error handling, and security boundaries—so you can focus on your tool's logic.

Works with Claude Code, Cursor, Windsurf, and any MCP-compatible client.

---

🚀 Why this boilerplate?

Most MCP tutorials show you a "toy" server. This repo gives you a production-grade foundation.

🛡️ Secure by Design

SSRF Protection: Blocks requests to private/internal networks (IPv4 + IPv6), including cloud metadata endpoints (169.254.169.254). DNS resolution is checked to prevent rebinding.
JWT Security: Algorithm validation rejects alg:none, HS384, and RS256 downgrade attacks. Expiry and tampering are verified with constant-time comparison.
HMAC-SHA256 Webhook Signatures: Outbound webhooks are signed with X-Webhook-Signature when a secret is configured.
DNS Rebinding Protection: HTTP transport validates Host header against an allowlist.
Sandboxed File Access: Prevents AI from reading/writing outside allowed directories, with symlink escape detection.
Strict Input Validation: All tool inputs are validated with Zod schemas.
Injection Protection: SQLite queries use strict parameter binding.
Security tested: 30+ security-focused test cases covering OWASP top threats (SSRF, injection, path traversal, auth bypass).

🔌 Built for Real Projects

Authentication: Built-in strategies for API Key and JWT (configurable per env).
Rate Limiting: Token bucket algorithm to prevent abuse.
Observability: Structured JSON logging (via pino) ready for CloudWatch/Datadog.

⚡ Developer Experience (DX)

Type-Safe: strict: true TypeScript configuration, ESM, fully typed.
Testing: 228 tests (unit, integration, and E2E) with Vitest, including 30+ security-focused cases.
Dockerized: Multi-stage Dockerfile for immediate deployment.

---

📦 What's Included

Reference Implementations

Includes 6 fully-typed tools to copy-paste patterns from:

database-query: Secure SQLite operations.
api-connector: Fetch data from external REST APIs.
file-manager: Safe file system operations (5 sub-tools).
cache-store: TTL-based key-value cache with namespaces (5 sub-tools).
semantic-search: Local RAG with embeddings (3 tools + 2 resources + 1 prompt).
webhook-notifier: Async webhook delivery with task tracking (4 tools + 2 resources + 1 prompt).

---

🏁 Quick Start

Prerequisites

Node.js 22+

WSL2 users: Use Node.js installed inside WSL, not Windows. See Troubleshooting.

npm 9+

1. Setup

git clone <your-repo-url> my-mcp-server
cd my-mcp-server
npm install

2. Configure Environment

cp .env.example .env
# Edit .env if needed — defaults work out of the box

3. Seed Sample Database

npm run db:seed  # Populates local SQLite for testing

Note: If the server is already running, restart it after seeding to pick up the new database.

4. Build

npm run build  # Compiles TypeScript to dist/

5. Run Development Server

npm run dev
# Starts server in hot-reload mode

6. Verify with Inspector

npm run inspector
# Opens interactive debugger in your browser (uses dist/index.js)

---

🔧 Connecting to Clients

Claude Code

Copy the example config to your project root:

cp .mcp.json.example .mcp.json
# Edit paths in .mcp.json to match your setup

Or add manually to your .mcp.json:

{
  "mcpServers": {
    "mcp-starter-kit": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "LOG_LEVEL": "info",
        "DB_PATH": "./data/sample.db",
        "SANDBOX_ROOT": "./data/sandbox"
      }
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "my-production-server": {
      "command": "node",
      "args": ["/absolute/path/to/my-mcp-server/dist/index.js"]
    }
  }
}

Cursor, Windsurf, & Others

See docs/SETUP.md for detailed connection guides.

---

📂 Project Architecture

Designed for scalability:

mcp-starter-kit/
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts             # Central MCP registry
│   ├── config/env.ts         # Environment variable validation (Zod)
│   ├── tools/
│   │   ├── database-query/   # SQLite CRUD tool
│   │   ├── api-connector/    # REST API tool
│   │   ├── file-manager/     # Sandboxed file operations tool
│   │   ├── cache-store/      # TTL-based key-value cache
│   │   ├── semantic-search/  # Local RAG with embeddings
│   │   └── webhook-notifier/ # Async webhook delivery
│   ├── lib/                  # Shared utilities (Logger, Guardrails)
│   ├── middleware/            # Auth & rate limiting
│   └── transport/            # stdio and HTTP transports
├── tests/                    # Integration tests & helpers
├── scripts/                  # CLI tools (db:seed, create-tool)
├── docs/                     # Detailed documentation
├── docker/                   # Dockerfile & docker-compose
└── data/                     # Sample DB & sandbox directory

---

📜 Documentation

| Document | Description | |----------|-------------| | SETUP.md | Detailed setup, environment variables, client configuration | | CUSTOMIZATION.md | Step-by-step guide to creating new tools | | DEPLOYMENT.md | Deploy via npm, Docker, or cloud services | | ARCHITECTURE.md | Design decisions, security model, and data flow | | TROUBLESHOOTING.md | Common errors and solutions | | TESTING.md | Test suite organization, writing tests, security checklist | | SECURITY.md | Security policy, vulnerability reporting, feature inventory |

---

🛠️ Scripts

| Command | Description | |---------|-------------| | npm run dev | Start with hot-reload (tsx watch) | | npm run build | Build to dist/ (tsup) | | npm start | Run built server (stdio) | | npm run start:http | Run built server (HTTP) | | npm test | Run all tests | | npm run lint | Lint with ESLint | | npm run typecheck | Type-check with tsc | | npm run inspector | Open MCP Inspector | | npm run db:seed | Seed sample SQLite database | | npm run create-tool | Scaffold a new tool | | npm run test:coverage | Run tests with coverage report |

---

License

Not affiliated with, endorsed by, or certified by Anthropic or the Agentic AI Foundation.

mcp-starter-kit