Servidor MCP del Sistema de RR. HH.

Un prototipo no oficial de servidor MCP que proporciona funcionalidad de sistema de RR. HH. con validación de token de Okta. Solo para fines de evaluación y pruebas.

📚 Documentación

Documentación completa disponible en la carpeta docs/:

• docs/RAILWAY_README.md - Desplegar en Railway.com (3 pasos) 🚀

• docs/DOCKER_QUICK_START.md - Ejecutar localmente con Docker 🐳

• docs/README_INTEGRATION.md - Usar el servidor desplegado 🔌

• docs/CLAUDE.md - Guía para desarrolladores y arquitectura 💻

• docs/INDEX.md - Índice completo de documentación 📖

Related MCP server: Keka MCP Server

Descripción general

El servidor MCP del Sistema de RR. HH. proporciona:

• ✅ Búsqueda de información de empleados

• ✅ Listado del directorio de empleados

• ✅ Acceso a información de nómina

• ✅ Gestión de solicitudes de tiempo libre

• ✅ Validación de token OAuth 2.0 de Okta para todas las llamadas a herramientas

• ✅ Soporte para streaming HTTP/NDJSON (FastMCP)

• ✅ Listo para despliegue en Railway 🚀

Autenticación

Este servidor valida los tokens de acceso de Okta para todas las llamadas a herramientas (excepto initialize):

• Origen del token: Servidor de autorización de Okta

• Validación: Firma JWT, expiración, reclamaciones de audiencia (audience claims)

• Encabezado de autorización: Authorization: Bearer <access_token>

Inicio rápido

# Setup
cp env.example .env
# Edit .env with your Okta credentials

# Install dependencies
pip install -r requirements.txt

# Run in HTTP mode (for Okta MCP Adapter)
python main.py --http 8001

Configuración

.env (Variables de entorno)

OKTA_DOMAIN=ijtestcustom.oktapreview.com
OKTA_AUTHORIZATION_SERVER_ID=auss2fth0mcIXHzVO1d7
OKTA_AUDIENCE=
OKTA_REQUIRED_SCOPES=
# When true (default), tools/list without auth returns 401. When false, allows unauthenticated tools/list (e.g. for gateway registration).
# PROTECTED_DISCOVERY=true

Herramientas disponibles

Ejemplos de uso

Directo mediante VS Code/Copilot

# Endpoint
http://localhost:8001/mcp

# Authorization
Authorization: Bearer <okta_access_token>

Mediante el adaptador de puerta de enlace MCP de Okta

# Gateway will:
# 1. Receive request from client
# 2. Validate Okta token
# 3. Forward to HR System MCP
# 4. Attach authorization header

Detalles de implementación

• Framework: FastMCP 3.0.0b1

• Servidor: Uvicorn (HTTP asíncrono)

• Protocolo: MCP (Model Context Protocol) con streaming NDJSON

• Validación de token: Validación JWT basada en JWKS con verificación de firma

• Caché: Claves JWKS cacheadas con TTL

Flujo de solicitud

Client Request
    ↓
Authorization Header (Okta token)
    ↓
Initialize (no token needed)
    ↓
tools/list (validate token)
    ↓
tools/call (validate token)
    ↓
Response

🚀 Opciones de despliegue

Vercel (Serverless) ⚡

Desplegar como función serverless: escalado automático, pago por uso

• ✅ Ideal para: Uso esporádico, escalado automático a cero

• ✅ Nivel gratuito: 100 GB de ancho de banda/mes

• ⚠️ Limitación: Tiempo de espera de 10 segundos (gratuito), 5 min (Pro)

• 📖 Guía: docs/VERCEL_README.md

Railway.com (Servidor tradicional) 🚂

Desplegar como servidor de larga ejecución: siempre activo, tiempo de espera ilimitado

• ✅ Ideal para: Tráfico constante, conexiones persistentes

• ✅ Nivel gratuito: 500 horas/mes ($5/mes después)

• ✅ Sin tiempo de espera: Duración de solicitud ilimitada

• 📖 Guía: docs/RAILWAY_README.md

Docker (Desarrollo local) 🐳

Ejecutar localmente con Docker: control total, pruebas

• 📖 Guía: docs/DOCKER_QUICK_START.md

docker-compose up -d

Recomendación:

• Use Vercel para un uso esporádico/impredecible (más barato, autoescalable)

• Use Railway para tráfico constante o si necesita tiempos de espera largos

Solución de problemas

Consulte docs/RAILWAY_DEPLOYMENT.md para obtener la guía completa de solución de problemas.

Soluciones rápidas:

• La validación del token falla: Verifique OKTA_DOMAIN y OKTA_AUTHORIZATION_SERVER_ID en .env

• Puerto ya en uso: Cambie el puerto en el comando de inicio: python main.py --http 8002

• Variables de entorno faltantes: Copie el ejemplo de .env y rellene los valores

• Error de obtención de JWKS: Verifique que el dominio de Okta y el ID del servidor de autorización sean correctos

Estructura del proyecto

hr-mcp-server/
├── main.py                    # FastMCP server with HTTP handler
├── requirements.txt           # Python dependencies
├── Dockerfile                 # Docker container definition
├── docker-compose.yml         # Docker Compose configuration
├── railway.json               # Railway deployment config
├── deploy-railway.sh          # Deployment helper script
├── test_server.sh            # Server test script
├── auth/                      # Authentication module
│   ├── __init__.py
│   └── okta_validator.py     # Okta token validation
└── docs/                      # Documentation
    ├── INDEX.md              # Documentation index
    ├── RAILWAY_README.md     # Railway quick start
    ├── RAILWAY_DEPLOYMENT.md # Complete deployment guide
    ├── DOCKER_QUICK_START.md # Docker reference
    ├── README_INTEGRATION.md # Usage guide
    ├── CLAUDE_CODE_SETUP.md  # Claude Code setup
    ├── CLAUDE.md             # Developer documentation
    └── ...more docs

Consulte docs/INDEX.md para obtener la guía de documentación completa.

Pruebas

# Using curl with Okta token
curl -X POST http://localhost:8001/mcp \
  -H "Authorization: Bearer <your_okta_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

📖 Documentación

Para obtener la documentación completa, consulte la carpeta docs/:

• Primeros pasos - Índice de documentación

• Desplegar en Railway - Guía de despliegue en la nube

• Ejecutar con Docker - Desarrollo local

• Guía de integración - Cómo usar el servidor

• Guía para desarrolladores - Arquitectura y desarrollo

Referencias

• Especificación MCP

• Documentación de FastMCP

• Documentación para desarrolladores de Okta

• Documentación de Railway

Estado

⚠️ Prototipo no oficial - Solo para evaluación y pruebas. No apto para uso en producción.

Licencia: Apache 2.0