MCP Node.js Boilerplate

Boilerplate para crear un cliente MCP y un servidor MCP con Node.js + TypeScript, usando Express en el lado HTTP. Admite tanto

• stdio — el cliente abre el servidor como proceso hijo, ideal para hosts MCP que se ejecutan en la máquina local

• Streamable HTTP — el endpoint está en /mcp y se puede exponer como HTTPS con Cloudflare Tunnel

• mock tools para CRUD de users

• resource estático users://all y resource template users://{id}

• prompt summarize-users

• CLI client para discovery, llamar a tools, leer resources y solicitar prompts

Los datos iniciales están en src/data/users.json y se cargan en memoria al abrir el servidor. Las modificaciones mediante CRUD no sobrescriben el archivo y se restablecen al reiniciar el proceso.

Requirements

• Node.js 20 o superior

• npm

• cloudflared solo si se necesita un túnel HTTPS

Related MCP server: MCP TypeScript Starter

Instalación

npm install

Comprobar build y test:

npm run check

Estructura importante

src/
├── client/
│   └── client.ts          # MCP CLI client ใช้ได้ทั้ง stdio และ HTTP
├── data/
│   └── users.json         # mock seed data
├── lib/
│   └── api-client.ts      # shared Axios instance สำหรับ upstream APIs
├── services/
│   └── user-service.ts    # business logic กลางสำหรับ MCP capabilities
└── server/
    ├── mcp.ts             # ประกอบ server และ capability registrations
    ├── tools/
    │   └── user-tools.ts
    ├── resources/
    │   └── user-resources.ts
    ├── prompts/
    │   └── user-prompts.ts
    ├── schemas/
    │   └── user.ts        # shared MCP output schema
    ├── repository.ts      # in-memory CRUD repository
    ├── stdio.ts           # stdio entry point
    └── http.ts            # Express + Streamable HTTP entry point
scripts/
└── build.mjs              # compile TypeScript และ copy mock JSON ไป dist

La factory en mcp.ts se comparte entre ambos transports, por lo que las capacidades del servidor no difieren. Tools, Resources y Prompts llaman al UserService central en lugar de acoplarse directamente al repositorio.

Llamar a una API externa con Axios

El proyecto incluye una instancia compartida de Axios en src/lib/api-client.ts con base URL, timeout y token Bearer opcional. Se puede importar y usar en tools o services:

import { apiClient } from "../../lib/api-client.js";

const response = await apiClient.get("/users");
console.log(response.data);

Configurar al abrir el servidor:

API_BASE_URL=https://api.example.com \
API_TIMEOUT_MS=10000 \
API_TOKEN=your-token \
npm run server:http

Ejemplo de uso en una MCP tool:

server.registerTool(
  "list-upstream-users",
  {
    description: "List users from the configured upstream API",
    inputSchema: z.object({}),
  },
  async () => {
    const { data } = await apiClient.get("/users");
    return {
      content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
      structuredContent: { users: data },
    };
  },
);

Si no se define API_BASE_URL, aún se puede pasar una URL absoluta directamente a Axios. Evita registrar API_TOKEN en logs y guarda el token en un secret manager al desplegar en producción.

Cómo ejecutar en modo stdio

Normalmente no hace falta abrir un servidor stdio por separado, porque el cliente o el host MCP lanzan el proceso por sí mismos.

Ejecutar el cliente demo, que abre el servidor, descubre capacidades, llama a tools, lee resources y solicita prompts:

npm run client:stdio -- demo

Abrir el servidor directamente para esperar a un host MCP:

npm run server:stdio

Precaución: stdio usa stdout como canal JSON-RPC, por lo que los logs del servidor deben escribirse a través de stderr, por ejemplo con console.error.

Ejemplo de configuración para un host MCP, cambiando /absolute/path/to/mcp-boilerplate por la ruta real:

{
  "mcpServers": {
    "mock-users": {
      "command": "node",
      "args": [
        "--import",
        "tsx",
        "/absolute/path/to/mcp-boilerplate/src/server/stdio.ts"
      ],
      "cwd": "/absolute/path/to/mcp-boilerplate"
    }
  }
}

O compilar primero y usar JavaScript sin depender de tsx en tiempo de ejecución:

npm run build
npm run start:stdio

Configuración tras el build:

{
  "mcpServers": {
    "mock-users": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-boilerplate/dist/server/stdio.js"
      ],
      "cwd": "/absolute/path/to/mcp-boilerplate"
    }
  }
}

Cómo ejecutar con Express HTTP

Terminal 1 — abrir el servidor:

npm run server:http

Valores por defecto:

• MCP endpoint: http://127.0.0.1:3000/mcp

• health check: http://127.0.0.1:3000/health

Terminal 2 — ejecutar el cliente HTTP:

npm run client:http -- demo

Se puede cambiar el puerto o el host con variables de entorno:

HOST=127.0.0.1 PORT=4000 npm run server:http
MCP_URL=http://127.0.0.1:4000/mcp npm run client:http -- demo

Para un build de producción:

npm run build
npm run start:http

Habilitar HTTPS con Cloudflare Tunnel

En este ejemplo, HTTPS termina en Cloudflare; el servidor Express sigue escuchando HTTP solo en la máquina local.

En macOS, instalar cloudflared:

brew install cloudflared

Terminal 1 — abrir el servidor MCP HTTP:

npm run server:http

Terminal 2 — abrir un Quick Tunnel:

cloudflared tunnel --url http://127.0.0.1:3000

cloudflared mostrará una URL temporal, por ejemplo:

https://random-words.trycloudflare.com

El endpoint MCP externo será, por tanto:

https://random-words.trycloudflare.com/mcp

Terminal 3 — probar a través del túnel HTTPS:

MCP_URL=https://random-words.trycloudflare.com/mcp npm run client:http -- demo

Quick Tunnel es adecuado solo para desarrollo, y Cloudflare indica que no admite SSE. Por eso este boilerplate configura el response mode en auto, de modo que los comandos CRUD/discovery habituales responden con JSON, pero no se debe usar Quick Tunnel para probar funciones que requieran streaming, como suscripciones de larga duración. Para producción, usa un named tunnel, tu propio hostname, autenticación y autorización.

Al usar un hostname personalizado, añádelo a la allowlist:

ALLOWED_HOSTS=mcp.example.com npm run server:http

Varios hostnames separados por comas:

ALLOWED_HOSTS=mcp.example.com,mcp-staging.example.com npm run server:http

localhost, 127.0.0.1, ::1 y *.trycloudflare.com ya están permitidos para desarrollo.

Comandos del cliente MCP

Se usa el mismo formato tanto con client:stdio como con client:http; solo cambia el nombre del script.

Ver tools:

npm run client:stdio -- list-tools
npm run client:http -- list-tools

Ver resources o prompts:

npm run client:stdio -- list-resources
npm run client:stdio -- list-prompts

Llamar a las CRUD tools:

npm run client:stdio -- call list-users '{}'
npm run client:stdio -- call get-user '{"id":"1"}'
npm run client:stdio -- call create-user '{"name":"Margaret Hamilton","email":"margaret@example.com","role":"developer"}'
npm run client:stdio -- call update-user '{"id":"1","role":"viewer"}'
npm run client:stdio -- call delete-user '{"id":"3"}'

Leer resources:

npm run client:stdio -- read users://all
npm run client:stdio -- read users://1

Solicitar un prompt:

npm run client:stdio -- prompt summarize-users '{"tone":"detailed"}'

Para otra URL HTTP, define MCP_URL:

MCP_URL=https://mcp.example.com/mcp npm run client:http -- call list-users '{}'

Nota para stdio: cada comando CLI lanza un nuevo proceso de servidor, por lo que siempre parte de los datos mock originales. Si quieres que las operaciones CRUD sean continuas, usa un host MCP que mantenga la misma conexión, o abre el servidor HTTP y llama a través de client:http.

Tools, resources y prompt disponibles

Variables de entorno

Los valores de ejemplo están en .env.example. El proyecto no carga automáticamente el archivo .env; exporta las variables o ponlas delante del comando, como en los ejemplos anteriores.

Notas de seguridad

• Este ejemplo no incluye autenticación ni autorización; no expongas un endpoint público con datos reales.

• La validación de Host y Origin solo permite localhost, TryCloudflare y los valores de ALLOWED_HOSTS.

• El repositorio mock está en memoria y, a propósito, no persiste datos.

• Para producción, añade auth, rate limiting, audit logging, una base de datos persistente y una configuración TLS/trust-proxy adecuada para el sistema real.

Todos los scripts

npm run dev:stdio       # stdio server พร้อม watch mode
npm run dev:http        # Express HTTP server พร้อม watch mode
npm run server:stdio    # stdio server จาก TypeScript
npm run server:http     # Express HTTP server จาก TypeScript
npm run client:stdio -- demo
npm run client:http -- demo
npm run build
npm run start:stdio     # รัน dist หลัง build
npm run start:http      # รัน dist หลัง build
npm test
npm run check

Referencias: MCP TypeScript SDK, Cloudflare Quick Tunnels