MCP Boilerplate for Node.js

This provides some common code for creating a Model Context Protocol (MCP) server in Node.js.

Usage

npm install @tigerdata/mcp-boilerplate

Requires Node.js 22.15 or later.

See tiger-skills-mcp-server for an example MCP server using this boilerplate.

Protocol versions

The servers from httpServerFactory and stdioServerFactory serve the 2026-07-28 MCP protocol and the 2025 protocol versions (up to 2025-11-25) on the same endpoint. The client selects the version.

The HTTP server does not use sessions (the 2026-07-28 protocol has none, and they are optional in the 2025 protocol). Each HTTP request gets a new server instance. Thus, the server cannot send requests to a 2025 client (for example, elicitation or sampling), and cannot send it notifications outside of a request (for example, list_changed).

Upgrading from v1 of the MCP SDK

This package uses v2 of the MCP TypeScript SDK (@modelcontextprotocol/server). If your server uses SDK types or APIs directly, see the SDK migration guide. In particular:

• zod must be ^4.2.0.
• httpServerFactory no longer has the stateful option. Remove stateful: false from your options.
• additionalSetup receives a v2 McpServer.
• Resource callbacks (read, list) receive a v2 ServerContext (ctx) instead of the v1 extra object. For example, extra.signal is now ctx.mcpReq.signal.

DNS Rebinding Protection

MCP servers reachable over HTTP can be targeted by DNS rebinding attacks, where a malicious website bypasses the browser same-origin policy by pointing a domain at a localhost (or otherwise private) address to reach a local server. The MCP SDK guards against this by validating the Host header against an allow-list.

This check is most useful for localhost / development servers without HTTPS or authentication. Hosted servers served on public hostnames generally don't need it (and would reject legitimate traffic unless every allowed hostname is listed), so httpServerFactory leaves it disabled by default — it is opt-in via the dnsRebindingProtection option (scoped to the MCP and API mount paths):

import { httpServerFactory } from '@tigerdata/mcp-boilerplate';

await httpServerFactory({
  name: 'my-server',
  context,
  // Omitted (default): disabled, UNLESS MCP_ALLOWED_HOSTS is set — in which
  //   case protection is enabled using that env var's allow-list.
  // true: enabled. Uses the MCP_ALLOWED_HOSTS allow-list when set, otherwise
  //   localhost-only (localhost, 127.0.0.1, [::1]).
  // string[]: enabled with this exact allow-list (MCP_ALLOWED_HOSTS ignored).
  //   Hostnames only, without ports; use [::1] for IPv6.
  // false: disabled. Always wins, even if MCP_ALLOWED_HOSTS is set.
  dnsRebindingProtection: true,
});

The MCP_ALLOWED_HOSTS environment variable can both enable and configure protection without touching code: set it to a comma-separated list of hostnames (e.g. localhost,127.0.0.1,[::1]) and protection turns on using that list. It is consulted whenever dnsRebindingProtection is omitted or true, but is ignored when an explicit string[] is passed (that list wins) or when false is passed (protection stays off).

Binding to a specific network interface

Separately from Host header validation, you can restrict which network interface the server's socket accepts connections on via the host option (forwarded to app.listen()). Binding to loopback is an OS-level defense that makes the port unreachable from other machines entirely — useful for localhost/development servers:

await httpServerFactory({
  name: 'my-server',
  context,
  host: '127.0.0.1', // only accept connections on loopback
});

Defaults to the HOST environment variable, or all available interfaces when unset. This is independent of dnsRebindingProtection and is ignored when an external app is provided (the caller owns the server lifecycle).

Skills

Add skills support to your MCP server by leveraging the skills submodule in @tigerdata/mcp-boilerplate/skills. See the Skills README for details.

Logging

The exported log helper writes to the console (via stderr, to avoid interfering with the stdio MCP transport) and emits OpenTelemetry log records. The CONSOLE_LOG_LEVEL environment variable sets the minimum severity written to the console: debug (the default, writes everything), info, warn, error, or none to disable console output entirely. OpenTelemetry log records are always emitted regardless of this setting.

Eslint Plugin

This project includes a custom ESLint plugin to guard against the problematic use of optional parameters for tool inputs. Doing so leads to tools that are incompatible with certain models, such as GPT-5.

Add to your eslint.config.mjs:

import boilerplatePlugin from '@tigerdata/mcp-boilerplate/eslintPlugin';
export default [
  // ... your existing config
  {
    plugins: {
      'mcp-boilerplate': boilerplatePlugin,
    },
    rules: {
      'mcp-boilerplate/no-optional-tool-params': 'error',
    },
  },
];

Development

Build

To build the TypeScript project:

./bun run build

This compiles the TypeScript files from src/ to JavaScript in dist/.

Watch Mode

To run TypeScript compilation in watch mode (rebuilds on file changes):

./bun run watch

Linting

This project uses ESLint for code linting with TypeScript support.

To run the linter:

./bun run lint

To automatically fix linting issues where possible:

./bun run lint --write

Continuous Integration

The project includes GitHub Actions that automatically run linting checks on all pushes and pull requests to ensure code quality standards are maintained.