My First SSE MCP Server
Servidor de ejemplo basado en Model Context Protocol (MCP) que expone herramientas
sobre HTTP + Server-Sent Events (SSE) para interactuar con una API local de usuarios
y de estado.
Este repo está pensado como plantilla/boilerplate para crear más MCP servers en Node
basados en Express + SSE. La idea es clonar este proyecto, cambiar el nombre y adaptar
las tools de ejemplo a tu propio dominio y APIs.
Índice / Table of Contents
- 🇪🇸 Documentación en Español
- 🇬🇧 English Documentation
🇪🇸 Documentación en Español
Descripción
myfirstmcpserver es un servidor MCP que:
- Expone un endpoint SSE (
GET /sse) y uno HTTP (POST /messages) usando Express. - Usa el SDK oficial
@modelcontextprotocol/sdkpara registrar herramientas MCP. - Se conecta a una API HTTP externa (por defecto
http://localhost:3001) para operaciones
de red y de usuarios.
Para más detalle técnico, consulta la spec interna en docs/spec.md.
Características principales
- Transporte SSE: integración basada en
SSEServerTransportdel SDK MCP. - Agrupación por dominio:
networkTools: herramientas relacionadas con conectividad y estado de una API.userTools: herramientas para listar y crear usuarios vía API externa.- Diseño extensible: fácil añadir nuevos grupos de tools o nuevas operaciones.
> Nota: aunque el nombre del repo haga referencia a STDIO, esta plantilla está basada
> en Express + SSE, no en STDIO puro.
Cómo usar esta plantilla
- Clona este repositorio o úsalo como template en GitHub.
- Cambia el nombre del paquete y la descripción en
package.jsonsi lo deseas. - Opcionalmente, cambia el
namedelMcpServerensrc/config/server.js. - Adapta o elimina las tools de ejemplo en:
-src/tools/networkTools.js
-src/tools/userTools.js
Crea nuevos módulosinitializeXToolssiguiendo el mismo patrón para tu dominio. - Configura la variable de entorno
API_BASE_URLpara apuntar a tu API real. - Ajusta la documentación del
README.mdy dedocs/spec.mdpara tu nuevo proyecto.
Requisitos
- Node.js ≥ 18 (se usa
fetchnativo de Node). - npm (gestor de paquetes).
Instalación
Desde la raíz del proyecto:```bash
npm install
### Ejecución
- Modo desarrollo (con `nodemon`):```bash
npm run dev
- Modo normal:```bash
npm start
Por defecto el servidor se levanta en `http://localhost:3000`. El endpoint SSE es:
- `GET http://localhost:3000/sse`
Y el endpoint de mensajes MCP es:
- `POST http://localhost:3000/messages`
### Uso con un cliente MCP
Este servidor está pensado para ser consumido por un **cliente MCP** que soporte
el transporte SSE definido en el SDK (`SSEServerTransport`).
De forma general, el cliente debe:
- Abrir una conexión SSE contra `GET /sse`.
- Enviar peticiones MCP (tools) en formato JSON a `POST /messages`.
Consulta la documentación del cliente MCP que estés usando para ver cómo configurar
un endpoint SSE externo.
### Herramientas MCP disponibles
Las tools se registran en la instancia de `McpServer` y se describen con más detalle
en `docs/spec.md`. Resumen rápido:
- 🔗 **Network Tools** (`src/tools/networkTools.js`):
- `ping({ url })`: hace un `fetch(url)` y devuelve el código de estado o un error.
- `apiStatus()`: llama a `http://localhost:3001/status` y devuelve el JSON de estado.
- 👤 **User Tools** (`src/tools/userTools.js`):
- `getUsers()`: obtiene la lista de usuarios desde `http://localhost:3001/users`.
- `createUser({ name, email })`: crea un usuario nuevo separando nombre y apellidos
y haciendo `POST` a `http://localhost:3001/users`.
### API externa
Este proyecto **no incluye** la implementación de la API externa en `http://localhost:3001`,
solo la consume. Se espera que exista un servicio con al menos:
- `GET /status` — Devuelve información de estado.
- `GET /users` — Devuelve un array de usuarios.
- `POST /users` — Crea un nuevo usuario con el body JSON adecuado.
Consulta `docs/spec.md` para ver ejemplos de estructuras de datos.
---
## 🇬🇧 English Documentation
### Overview
`myfirstmcpserver` is a **Model Context Protocol (MCP)** server that:
- Exposes an SSE endpoint (`GET /sse`) and an HTTP endpoint (`POST /messages`) using **Express**.
- Uses the official `@modelcontextprotocol/sdk` to register MCP tools.
- Connects to an external HTTP API (by default `http://localhost:3001`) for network and
user-related operations.
For a deeper technical description, check the internal spec in `docs/spec.md`.
### Features
- **SSE transport** using the SDK `SSEServerTransport`.
- **Domain-based tools grouping**:
- `networkTools`: connectivity and API health checks.
- `userTools`: listing and creating users through the external API.
- **Extensible design**: easy to add new tool groups or operations.
> Note: even if the repo name mentions STDIO, this template is built on
> **Express + SSE**, not on pure STDIO transport.
### How to use this template
1. Clone this repository or use it as a *template* on GitHub.
2. Update the package `name` and `description` in `package.json` if needed.
3. Optionally change the `name` of the `McpServer` in `src/config/server.js`.
4. Adapt or remove the example tools in:
- `src/tools/networkTools.js`
- `src/tools/userTools.js`
and create new `initializeXTools` modules following the same pattern.
5. Configure the `API_BASE_URL` environment variable to point to your real API.
6. Adjust this `README.md` and `docs/spec.md` to describe your concrete project.
### Requirements
- **Node.js** ≥ 18 (uses Node’s built-in `fetch`).
- **npm** as package manager.
### Setup
From the project root:```bash
npm install
Running
- Development mode (with
nodemon):```bash
npm run dev
- Normal mode:```bash
npm start
By default the server listens on http://localhost:3000. Main endpoints:
GET http://localhost:3000/sse— SSE endpoint for MCP.POST http://localhost:3000/messages— MCP messages endpoint.
Using it from an MCP client
This server is intended to be used by an MCP client supporting SSE transport
as implemented by the SDK.
In general, the client should:
- Open an SSE connection to
GET /sse. - Send MCP tool requests as JSON to
POST /messages.
Please refer to your MCP client documentation for the exact configuration format
to point it at an external SSE MCP server.
Available MCP tools
Tools are registered on the McpServer instance. See docs/spec.md for full details.
Quick summary:
- 🔗 Network Tools (
src/tools/networkTools.js): ping({ url }): performsfetch(url)and returns the HTTP status code or an error.apiStatus(): callshttp://localhost:3001/statusand returns the status JSON.- 👤 User Tools (
src/tools/userTools.js): getUsers(): gets the user list fromhttp://localhost:3001/users.createUser({ name, email }): creates a new user splitting full name into
first/last and sending aPOSTtohttp://localhost:3001/users.
External API
This project does not include the implementation of the external API at
http://localhost:3001; it just consumes it. It expects at least:
GET /status— Returns general status information.GET /users— Returns an array of users.POST /users— Creates a new user with the appropriate JSON body.
You can find example payloads in docs/spec.md.
Made by Enrique Rodriguez Vela
