MCP Template

Production-ready Model Context Protocol server template in TypeScript — SOLID architecture, dynamic tool registration, dual transport (stdio + HTTP), and pluggable authentication.

Clone it, drop a file in src/tools/, and you have a new tool. No registry to edit, no boilerplate to wire.

---

Highlights

• 🔌 Drop-in tools — create src/tools/<name>.tool.ts and it's auto-discovered and registered at startup.
• 🧱 SOLID by design — clear seams between config, transport, registry, auth, and tools; dependencies injected, never reached for globally.
• 🚦 Two transports — stdio for local clients (Claude Desktop, Claude Code) and Streamable HTTP for remote deployments, from the same code.
• 🔐 Auth in both directions — protect the server with an API key and consume external APIs with a key, both toggled by env.
• ✅ Quality baked in — strict TypeScript, Zod validation, structured logging (pino), Vitest, ESLint + Prettier, GitHub Actions, Docker.

Quick start

npm install
cp .env.example .env

npm run dev            # stdio transport, hot reload
# or
TRANSPORT=http npm run dev

Build and run for production:

npm run build
npm start

Creating a tool

This is the whole workflow. Create a file ending in .tool.ts under src/tools/:

// src/tools/greet.tool.ts
import { z } from "zod";
import { defineTool } from "../core/tool.js";

export default defineTool({
  name: "greet",
  description: "Greets a person by name.",
  inputSchema: {
    name: z.string().min(1).describe("Who to greet"),
  },
  handler: ({ name }, { logger }) => {
    logger.debug({ name }, "greeting");
    return { content: [{ type: "text", text: `Hello, ${name}!` }] };
  },
});

Restart the server — greet is live. The args are fully typed from inputSchema, and the second argument is the injected ToolContext (config, logger, httpClient).

Need an external API? Use the injected client instead of fetch:

const data = await httpClient.get(`/resources/${id}`);

The bundled get-current-weather.tool.ts and get-forecast.tool.ts are working references: they consult the free Open-Meteo API (no key needed) through the injected client and a dedicated WeatherService.

Configuration

All config is validated at startup in src/config/env.ts. See .env.example for every supported variable and its defaults.

Authentication

Protect the server (inbound). Set REQUIRE_AUTH=true and MCP_API_KEY=.... HTTP clients then authenticate with Authorization: Bearer <key> or x-api-key: <key>. The check is a constant-time comparison and lives behind the AuthStrategy interface — add JWT/OAuth by writing a new strategy, no transport changes.

Consume an external API (outbound). Set EXTERNAL_API_BASE_URL / EXTERNAL_API_KEY. The shared HttpClient injects the key, applies timeouts and retries, and is handed to every tool via the context.

Using with Claude Desktop

Add to claude_desktop_config.json (stdio):

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

Architecture

src/
├── index.ts            Composition root: load config → pick transport
├── server.ts           Builds the McpServer and runs the registry
├── config/env.ts       Zod-validated environment (single source of truth)
├── core/
│   ├── tool.ts         ToolDefinition contract + defineTool() helper
│   ├── tool-registry.ts  Dynamic discovery & registration of *.tool.ts
│   ├── tool-context.ts   Dependency-injection container for handlers
│   └── logger.ts       Structured logging (to stderr, stdio-safe)
├── transports/         stdio + Streamable HTTP (with auth middleware)
├── auth/               AuthStrategy interface + API-key implementation
├── clients/            Shared HTTP client for outbound API calls
├── services/           Domain logic (e.g. WeatherService) used by tools
├── tools/              👈 your tools — one file each, auto-registered
└── utils/errors.ts     Typed errors

How SOLID shows up here:

• Single responsibility — one tool per file; registry, transport, config, and auth are each isolated.
• Open/closed — add a tool or an auth strategy by adding a file; nothing existing changes.
• Liskov — every tool is interchangeable behind ToolDefinition.
• Interface segregation — small, focused contracts (ToolDefinition, AuthStrategy).
• Dependency inversion — handlers depend on the injected ToolContext, never on globals.

Scripts

Script	Purpose
npm run dev	Run with hot reload (tsx)
npm run build	Compile to dist/
npm start	Run the compiled server
npm run typecheck	Type-check without emitting
npm run lint	ESLint
npm run format	Prettier (write)
npm test	Run the test suite (Vitest)

Docker

docker build -t mcp-template .
docker run -p 3000:3000 -e REQUIRE_AUTH=true -e MCP_API_KEY=secret mcp-template

License

MIT © Vitor Kaez