MCPController

MCPController es una aplicación MCP de gestión de médicos con un único administrador. ChatGPT se conecta mediante OAuth 2.1 con PKCE, el administrador inicia sesión, elige qué permisos de médicos conceder, y el servidor MCP expone herramientas de médicos respaldadas por MongoDB.

Arquitectura

ChatGPT
  ↓
OAuth
  ↓
Admin Login
  ↓
Admin Consent
  ↓
Granted Permissions
  ↓
MCP Access Token
  ↓
MCP /mcp
  ↓
Permission Check
  ↓
Doctor Tools
  ↓
MongoDB

Related MCP server: GPT MCP Service

Qué hace esta aplicación

• Un único administrador es dueño de todo el sistema.

• No hay registro público ni cambio de cuentas multiusuario.

• El administrador se autentica con credenciales de variables de entorno.

• La pantalla de consentimiento permite al administrador aprobar doctor:read, doctor:write y doctor:delete.

• El servidor MCP vuelve a comprobar los ámbitos aprobados en cada llamada a una herramienta.

• Los datos de los médicos se almacenan en MongoDB mediante un modelo simple de Mongoose.

Autenticación

La sesión del navegador es independiente del token Bearer de MCP.

• Sesión del navegador: cookie HTTP-only utilizada para la interfaz de administración y la pantalla de consentimiento.

• Token de acceso MCP: token Bearer utilizado por ChatGPT contra /mcp.

• OAuth utiliza el flujo de código de autorización con PKCE.

• Los códigos de autorización son de un solo uso y de corta duración.

• Los tokens de acceso y de actualización se almacenan con hash antes de guardarlos.

El inicio de sesión del administrador utiliza ADMIN_EMAIL y ADMIN_PASSWORD de .env.

Gestión de médicos

El modelo de dominio es intencionadamente pequeño:

• name - cadena obligatoria

• specialization - cadena obligatoria

• createdAt / updatedAt - gestionados por las marcas de tiempo de Mongoose

El CRUD de médicos se implementa en una capa de servicios y se reutiliza tanto en la API REST de administración como en la capa de herramientas MCP.

Flujo OAuth

1. ChatGPT abre el endpoint de autorización.

2. Si el administrador no está autenticado, el navegador va a /login.

3. El administrador inicia sesión.

4. La página de consentimiento muestra los permisos de médicos solicitados.

5. El administrador aprueba un subconjunto o deniega la solicitud.

6. El código de autorización se intercambia por un token de acceso.

7. ChatGPT utiliza ese token en /mcp.

Flujo de permisos

Los ámbitos solicitados se asignan a las herramientas MCP de la siguiente manera:

• doctor:read → list_doctors, get_doctor

• doctor:write → add_doctor, update_doctor

• doctor:delete → delete_doctor

El backend aplica los permisos dos veces:

• OAuth solo escribe los ámbitos aprobados en el código de autorización y el token.

• Cada herramienta MCP comprueba los ámbitos del token antes de tocar MongoDB.

Herramientas MCP

Variables de entorno

Usa un archivo .env en la raíz. La aplicación lo carga desde la raíz del proyecto.

Valores necesarios para npm run dev local (Vite en 5173, API en 3000):

NODE_ENV=development
PORT=3000
APP_URL=http://localhost:5173
API_URL=http://localhost:3000
MONGODB_URI=mongodb://127.0.0.1:27017/mcpcontroller
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=change-this-password
JWT_SECRET=change-this-to-a-long-random-secret
MCP_SERVER_NAME=MCPController
MCP_SERVER_VERSION=1.0.0

El código también admite variables de duración de token/sesión con valores predeterminados seguros:

• JWT_EXPIRES_IN

• AUTH_CODE_TTL_SECONDS

• ACCESS_TOKEN_TTL_SECONDS

• REFRESH_TOKEN_TTL_SECONDS

En Vercel, APP_URL y API_URL deben ser ambas el origen HTTPS público (ver Implementación más abajo).

Configuración local

1. Instala las dependencias:

npm install

2. Inicia MongoDB localmente.

3. Siembra datos de ejemplo:

npm run seed

4. Inicia la aplicación:

npm run dev

En desarrollo, el cliente React se ejecuta a través de Vite y envía las solicitudes de API al backend mediante proxy.

Pruebas

Ejecuta las comprobaciones automatizadas con:

npm test

Ejecuta la compilación del cliente con:

npm run build

La suite de pruebas actual cubre:

• inicio de sesión de administrador

• registro deshabilitado

• modelo de médico y servicio CRUD

• aprobación de ámbitos OAuth

• aplicación de permisos de herramientas MCP

• revocación de tokens

Conectar ChatGPT

Usa la URL de autorización expuesta por el servidor:

• /.well-known/oauth-authorization-server

• /.well-known/oauth-protected-resource

• /oauth/token

• /mcp

Flujo típico:

1. ChatGPT descubre los metadatos OAuth.

2. ChatGPT solicita autorización para el recurso MCP.

3. El navegador redirige a la pantalla de inicio de sesión del administrador.

4. El administrador revisa los permisos y hace clic en Permitir y conectar.

5. ChatGPT intercambia el código por tokens.

6. ChatGPT llama a las herramientas MCP usando el token Bearer.

Implementación

La aplicación es un único origen: Express sirve /api, /oauth, /mcp, el descubrimiento OAuth y la compilación de React.

Vercel

Este repositorio ya incluye vercel.json y api/index.js. Vercel ejecuta la aplicación Express como una única función serverless y reescribe cada ruta hacia ella.

1. MongoDB Atlas

1. Crea un clúster (el M0 gratuito es suficiente).

2. Crea un usuario de base de datos.

3. Acceso de red: permite 0.0.0.0/0 para que Vercel pueda conectarse (o añade las IPs de Vercel si lo prefieres).

4. Copia la cadena de conexión, por ejemplo:

mongodb+srv://USER:PASSWORD@cluster0.xxxxx.mongodb.net/mcpcontroller?retryWrites=true&w=majority

2. Implementa el proyecto

• Sube este repositorio a GitHub.

• En Vercel, importa el repositorio.

• Framework Preset: Other (déjalo). vercel.json establece la instalación y la compilación.

• Root Directory: déjalo como la raíz del repositorio (no lo configures como client o server).

• Versión de Node.js: 20.x o más reciente.

3. Variables de entorno en Vercel

Proyecto → Configuración → Variables de entorno. Configúralas para Producción (y Vista previa si usas URLs de vista previa).

No pongas ADMIN_PASSWORD ni JWT_SECRET en la aplicación React. El cliente solo habla con /api.

Si añades un dominio personalizado más tarde, cambia APP_URL y API_URL a https://your-domain.com y vuelve a implementar.

Genera JWT_SECRET con:

node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"

4. Primera implementación y siembra

1. Implementa.

2. Abre https://your-app.vercel.app/api/health — deberías ver { "ok": true, ... }.

3. Siembra MongoDB desde tu máquina, apuntando a Atlas (no a la función serverless de Vercel):

# In the project root, temporarily set MONGODB_URI to the Atlas URI in .env
npm run seed

La siembra crea la fila de usuario administrador, médicos de ejemplo y un cliente local de MCP Inspector. Después, inicia sesión en el sitio en vivo con ADMIN_EMAIL / ADMIN_PASSWORD.

5. Conectar ChatGPT

Usa el origen implementado:

• https://your-app.vercel.app/.well-known/oauth-authorization-server

• https://your-app.vercel.app/.well-known/oauth-protected-resource

• https://your-app.vercel.app/mcp

En ChatGPT (o MCP Inspector), añade esa URL de MCP. ChatGPT abrirá las pantallas de inicio de sesión y consentimiento en el mismo dominio, y luego llamará a /mcp con un token Bearer.

Implementación por CLI (opcional)

npm i -g vercel
vercel login
vercel env pull   # optional: sync env locally
vercel --prod

Después de la primera implementación de producción, copia la URL en APP_URL y API_URL si usaste un marcador de posición, y vuelve a implementar para que los metadatos OAuth apunten al origen real.

Notas de seguridad

• No expongas ADMIN_PASSWORD ni JWT_SECRET al navegador.

• Mantén los tokens OAuth con hash en la base de datos.

• Solo aprueba los ámbitos que el administrador realmente quiera que ChatGPT use.

• Revoca el acceso cuando la conexión ya no deba ser de confianza.

• El inicio de sesión de administrador existe solo para autorizar a ChatGPT y gestionar datos de médicos; no hay flujo de registro público.

Datos de siembra

El script de siembra crea:

• médicos de ejemplo

• un cliente OAuth de ejemplo para uso local con inspector

No crea usuarios de demostración ni codifica credenciales de administrador.