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.

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

Feature	This Boilerplate	Basic Tutorials
Transport	HTTP (SSE) + Stdio	Stdio only
Validation	Zod Schemas	Manual / None
Logging	Structured JSON	console.log
Error Handling	Graceful + MCP Codes	Process crash
CI/CD	GitHub Actions	None

Reference Implementations

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

1. database-query: Secure SQLite operations.
2. api-connector: Fetch data from external REST APIs.
3. file-manager: Safe file system operations (5 sub-tools).
4. cache-store: TTL-based key-value cache with namespaces (5 sub-tools).
5. semantic-search: Local RAG with embeddings (3 tools + 2 resources + 1 prompt).
6. 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

MIT © 2026 Edge Craft Studio

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