Node.js MCP Server Template

A Fastify-based MCP TypeScript SDK 2.0 server template using the 2026-07-28 protocol over stdio and Streamable HTTP.

The built-in knowledge-base example demonstrates how the three server primitives work together:

  1. Call the search_documents Tool to find one of three MCP guides.
  2. Read the returned kb://documents/{documentId} Resource URI.
  3. Get the review_document Prompt to review the same document.

The example is deterministic and has no external data dependency. Tool results include both structuredContent and text content, resources are Markdown documents with stable URIs, and missing resources return a protocol-level Resource Not Found error.

The HTTP endpoint uses @modelcontextprotocol/fastify with Fastify 5. Its default localhost binding validates Host and Origin headers to protect local development servers from DNS rebinding.

Development

Requires Node.js 22 and npm 10. The repository's .nvmrc, packageManager, and package-lock.json define the supported local and CI toolchain.

nvm use
npm ci
npm run dev:stdio

Run the Streamable HTTP transport on http://localhost:8401/mcp:

cp .env.example .env
npm run dev:web

The local .env file is ignored by Git. PORT and --port must resolve to an integer from 1 to 65535.

Run the same verification stages used by CI:

npm run check

The individual stages are also available as npm run lint, npm run typecheck, npm run build, npm test, and npm run coverage. The production build preserves the source module layout as Node.js 22 ESM under build; build/index.js remains the executable entrypoint. Build-time aliases are rewritten to relative .js imports so the output runs directly in Node.js.

Inspect the npm package before publishing:

npm pack --dry-run

Usage

# Start with stdio transport (default)
node build/index.js

# Start with Streamable HTTP
node build/index.js web --port 8401

# Print CLI help or the package version
node build/index.js --help
node build/index.js --version

Environment Variables

  • PORT: Streamable HTTP port (default: 8401)
  • NODE_ENV: production for production builds or local for development
  • MCP_INSPECTOR_API_TOKEN: optional stable token for the MCP Inspector development session

License

MIT