ITM Platform
Conecta asistentes de IA a la gestión de proyectos y portafolios de ITM Platform: busca proyectos y servicios, revisa presupuestos, riesgos, incidencias y carga de trabajo del equipo, y crea o actualiza tareas, progreso y registros de tiempo usando tus propios permisos de ITM Platform.
Servidor MCP alojado
npx add-mcp 'https://api.itmplatform.com/v2/_/mcp/'Se instala en Claude Code, Codex, Cursor y más
Documentación
Servidor MCP de ITM Platform
Conecta ITM Platform a asistentes de IA a través del Model Context Protocol. El servidor MCP de ITM Platform permite a clientes compatibles con MCP buscar proyectos, inspeccionar presupuestos, resumir la salud del portafolio, crear tareas, registrar riesgos e incidencias, y actualizar detalles de proyectos usando tus permisos de ITM Platform.
Funciona con Claude, VS Code, Cursor, OpenAI Codex, Windsurf, JetBrains AI Assistant y cualquier otro cliente que soporte MCP.
- Documentación pública: developers.itmplatform.com/mcp
- Paquete npm: @itm-platform/mcp-server
- URL MCP alojada:
https://api.itmplatform.com/v2/_/mcp/
Inicio rápido
Conexión alojada con OAuth
Usa el servidor alojado si tu cliente de IA soporta servidores MCP remotos. No hay nada que instalar: añade la URL, inicia sesión con tu cuenta de ITM Platform y aprueba el acceso solicitado.
claude mcp add --scope user --transport http itm-platform https://api.itmplatform.com/v2/_/mcp/
Para otros clientes MCP, usa esta URL remota:
https://api.itmplatform.com/v2/_/mcp/
OAuth es la configuración recomendada para la mayoría de usuarios porque tu cliente de IA nunca ve tu contraseña o clave API de ITM Platform.
Después de añadir el servidor, abre tu cliente de IA, escribe /mcp donde se soporten comandos de barra, selecciona itm-platform y completa el inicio de sesión OAuth de ITM Platform cuando se te solicite.
Conexión local con clave API
Usa el paquete npm si prefieres ejecutar el servidor localmente, trabajar detrás de un firewall o necesitas conectarte a una instancia de ITM Platform autoalojada.
npx @itm-platform/mcp-server
Tu cliente MCP debe pasar estas variables de entorno al servidor:
| Variable | Valor |
|---|---|
ITM_API_URL | https://api.itmplatform.com |
ITM_COMPANY | El slug de tu empresa/cuenta |
ITM_API_KEY | Tu clave API personal de ITM Platform |
Ejemplo de configuración stdio:
{
"mcpServers": {
"itm-platform": {
"command": "npx",
"args": ["@itm-platform/mcp-server"],
"env": {
"ITM_API_URL": "https://api.itmplatform.com",
"ITM_COMPANY": "{your-account}",
"ITM_API_KEY": "your-api-key"
}
}
}
}
Para crear una clave API, inicia sesión en ITM Platform, abre Mi Perfil y genera una clave desde la sección Clave API.
Después de configurar el servidor local, reinicia tu cliente de IA y usa /mcp o la lista de servidores MCP del cliente para confirmar que itm-platform está conectado.
¿Qué Puede Hacer un Agente?
Desde consultas simples hasta flujos de trabajo totalmente automatizados entre sistemas, MCP desbloquea casos de uso progresivamente más potentes.
Consulta rápida -- Haz una pregunta, obtén una respuesta:
"¿Qué riesgos están abiertos en mi portafolio?"
Análisis de múltiples pasos -- El agente encadena múltiples herramientas y sintetiza resultados:
"Revisa cada proyecto que termine este trimestre. Señala cualquier proyecto con sobrecostos presupuestarios, riesgos abiertos de alto impacto o finalización de tareas por debajo del 60%."
Acciones masivas automatizadas -- El agente lee, decide y escribe en todos los proyectos:
"Para cada proyecto que aún esté en estado Planificación con fecha de inicio en el pasado, actualiza el estado a Ejecución y crea una tarea de lista de verificación de inicio asignada al gerente del proyecto."
Inteligencia programada -- Un agente se ejecuta según un horario sin intervención humana, extrayendo tareas vencidas cada lunes y publicando un resumen en Slack agrupado por gerente de proyecto.
Orquestación entre sistemas -- Combina el MCP de ITM Platform con otros servidores MCP (GitHub, Slack, Google Calendar, correo electrónico). Cuando un desarrollador fusiona un PR, un agente encuentra la tarea correspondiente en ITM Platform, la marca como completada y, si el proyecto alcanza el 100%, redacta un resumen de cierre y envía un correo al gerente del programa.
El servidor MCP se autentica como tú, llama a las APIs de ITM Platform y devuelve solo los datos que tu cuenta de ITM Platform tiene permitido acceder.
Capacidades
El servidor expone 47 herramientas MCP, 6 recursos y 4 plantillas de prompts.
Herramientas de Lectura
| Herramienta | Qué hace |
|---|---|
search_projects | Encuentra proyectos por nombre, estado, tipo o rango de fechas |
get_project | Recupera detalles del proyecto con conteos de subcomponentes y presupuesto opcional |
search_services | Encuentra servicios por nombre, estado, tipo o rango de fechas |
get_service | Recupera detalles del servicio con conteos de subcomponentes y presupuesto opcional |
list_project_tasks | Lista tareas de un proyecto con paginación |
get_task | Recupera el detalle completo de una sola tarea |
search_tasks | Busca tareas en todos los proyectos por nombre, estado, asignado, tipo o rango de fechas |
get_project_budget | Obtiene información de presupuesto, reales, ingresos, costos y margen |
get_project_purchases | Lista órdenes de compra de un proyecto con paginación |
get_project_revenues | Lista elementos de ingresos de un proyecto con paginación |
get_project_risks | Lista riesgos del proyecto con paginación |
get_project_issues | Lista incidencias del proyecto con paginación |
get_risk | Recupera el detalle completo de un solo riesgo, incluidos planes de mitigación y contingencia |
get_issue | Recupera el detalle completo de una sola incidencia, incluidos campos de resolución e impacto |
list_task_progress | Lista el historial de progreso (seguimiento) de una tarea |
get_task_effort | Obtiene el desglose de esfuerzo de una tarea por miembro del equipo y por categoría profesional; también funciona como lista del equipo de la tarea |
get_project_progress | Obtiene el informe de progreso del proyecto: curvas esperadas, de referencia y reales; opcionalmente las entradas completas de Seguimiento del proyecto |
list_service_activities | Lista actividades de un servicio con paginación |
get_service_purchases | Lista órdenes de compra de un servicio con paginación |
get_service_revenues | Lista elementos de ingresos de un servicio con paginación |
aggregate_portfolio | Agrupa y resume datos del portafolio |
query_datamart | Ejecuta consultas validadas de DataMart para análisis avanzados |
search_users | Encuentra usuarios y miembros del equipo; devuelve IsNonLoginUser para que los usuarios sin inicio de sesión (EmailAddress vacío) puedan ser identificados por UserId |
get_user | Recupera detalles del usuario |
get_reference_data | Recupera estados, tipos, prioridades y otras listas de referencia |
get_custom_fields | Recupera las definiciones de campos personalizados de la cuenta para proyectos, tareas, riesgos, incidencias, servicios, actividades, compras o ingresos |
get_custom_field_options | Recupera las opciones seleccionables de un campo personalizado de lista desplegable |
Herramientas de Escritura
| Herramienta | Qué hace |
|---|---|
create_project | Crea un proyecto (Waterfall o Kanban); el proyecto comienza con el estado predeterminado de la cuenta y el usuario creador como gerente del proyecto |
create_task | Añade una tarea, hito (KindId 1) o tarea de resumen (KindId 2); ParentId construye la jerarquía de Gantt en proyectos Waterfall; TaskManagers/TaskMembers asignan usuarios por nombre de usuario o UserId numérico (el id es la única opción para usuarios sin inicio de sesión) |
update_task | Actualiza campos de tarea como estado, fechas, tipo y padre; TaskManagers/TaskMembers añaden asignados por nombre de usuario o UserId numérico (solo añade, nunca elimina) |
create_task_progress | Reporta progreso en una tarea (porcentaje, evaluación, notas) con todos los efectos secundarios |
update_task_progress | Actualiza una entrada de progreso de tarea existente |
update_task_effort | Establece las horas estimadas (planificadas) de una tarea por usuario asignado; los datos de esfuerzo aceptado y facturación se conservan |
log_time_entry | Registra horas reales trabajadas en una tarea para un usuario y fecha; añade o reemplaza el total del día, mostrando los totales anteriores y nuevos |
create_project_progress | Crea una entrada de progreso a nivel de proyecto (Seguimiento): porcentaje, evaluación y descripción del estado; 100% cierra automáticamente el proyecto |
update_project_progress | Actualiza una entrada de progreso de proyecto existente |
create_risk | Registra un riesgo del proyecto |
update_risk | Actualiza campos de riesgo como estado, probabilidad, impacto, nivel y planes de mitigación o contingencia |
create_issue | Registra una incidencia del proyecto con tipo y estado de incidencia obligatorios |
update_issue | Actualiza campos de incidencia como estado, tipo y resolución |
update_project | Actualiza campos del proyecto como nombre, estado, fechas y prioridad |
create_service | Crea un servicio; comienza con el estado predeterminado de la cuenta |
update_service | Actualiza campos del servicio como nombre, estado, fechas y prioridad |
create_activity | Añade una actividad a un servicio (las actividades forman una lista plana) |
update_activity | Actualiza campos de actividad como estado y fechas |
bulk_update_task_status | Aplica un estado a hasta 100 tareas de un proyecto en una sola llamada |
bulk_update_activity_status | Aplica un estado a hasta 100 actividades de un servicio en una sola llamada |
Las operaciones de escritura confirman el estado guardado desde la API REST de ITM Platform. Los resultados de búsqueda respaldados por DataMart pueden tardar hasta 60 segundos en reflejar escrituras recientes. Los fallos de validación incluyen el mensaje accionable devuelto por REST en lugar de solo el estado HTTP.
Enrutamiento de fuentes de datos
Las lecturas provienen de DataMart siempre que DataMart tenga los datos (sin cuota, en todo el portafolio); REST se reserva para datos que DataMart no tiene, lecturas autoritativas de un solo elemento (get_task), lecturas de confirmación de escrituras y datos de referencia. Las escrituras siempre van a REST. Cuando DataMart adquiere un conjunto de datos, las herramientas GET correspondientes deben migrar a DataMart. Regla completa y mapa de enrutamiento actual: zz_Specifications/progress-history-reads-from-datamart.md.
Cuando la cuenta define campos personalizados, cada sesión se enriquece con contexto específico de la cuenta: el servidor lista las claves customFields de DataMart realmente en uso en las instrucciones de inicialización de MCP y en la descripción de la herramienta query_datamart, para que los agentes puedan leer y filtrar valores de campos personalizados sin descubrimiento previo.
Recursos y Prompts
Los recursos proporcionan a los clientes de IA contexto de solo lectura como esquemas de DataMart y calendarios de proyectos. Las plantillas de prompts proporcionan flujos de trabajo guiados para tareas de análisis comunes:
| Prompt | Con qué ayuda |
|---|---|
/project_status | Resume salud, tareas, riesgos, incidencias y presupuesto de un proyecto |
/portfolio_overview | Analiza estado del portafolio, metodología, presupuesto y patrones de entrega |
/team_workload | Revisa asignaciones y patrones de carga de trabajo |
/risk_analysis | Evalúa exposición al riesgo, incidencias e impacto presupuestario |
Autenticación y Permisos
El servidor MCP utiliza el mismo modelo de identidad y permisos que ITM Platform.
| Método de conexión | Autenticación | Mejor para |
|---|---|---|
| HTTP alojado | OAuth 2.1 con PKCE | La mayoría de usuarios y clientes de IA gestionados |
| stdio local | Clave API de ITM Platform | Ejecución local, redes con firewall, entornos autoalojados |
Las sesiones OAuth utilizan ámbitos:
| Ámbito | Permite |
|---|---|
mcp:read | Herramientas de solo lectura como buscar, obtener, listar, agregar y consultar |
mcp:write | Herramientas de lectura más herramientas de crear y actualizar |
Las sesiones con clave API utilizan los permisos completos del usuario de ITM Platform que generó la clave.
Acceso por licencia:
| Licencia | Acceso MCP |
|---|---|
| Administrador de Empresa | Acceso completo de lectura y escritura |
| Usuario Completo | Acceso completo de lectura y escritura |
| Gerente de Proyecto | Acceso de lectura y escritura limitado a proyectos gestionados |
| Miembro del Equipo | Bloqueado |
Tu asistente de IA no recibe tu contraseña o clave API de ITM Platform. Los datos del proyecto se devuelven al cliente de IA que elijas, por lo que la política de manejo de datos del proveedor de IA se aplica a cualquier dato que procese.
Configuración del Cliente
Usa la documentación pública para la configuración específica del cliente:
- Claude Code, Claude Desktop, VS Code, Cursor, Codex, Windsurf y JetBrains
- Conectar con OAuth
- Conectar con clave API
- Solución de problemas
Para cualquier cliente compatible con MCP, los dos valores de conexión son:
| Método | Valor |
|---|---|
| URL remota | https://api.itmplatform.com/v2/_/mcp/ |
| Comando local | npx @itm-platform/mcp-server |
Después de añadir cualquiera de las conexiones, abre el comando MCP del cliente o la lista de servidores. En clientes que soporten comandos de barra, escribe /mcp, selecciona itm-platform y autentícate cuando se te solicite.
Autoalojamiento
Para un servidor stdio local, configura ITM_API_URL, ITM_COMPANY y ya sea ITM_API_KEY o ITM_TOKEN.
Para un servidor HTTP con OAuth, configura:
| Variable | Descripción |
|---|---|
ITM_API_URL | URL de la puerta de enlace de la API de ITM Platform |
PORT | Puerto de escucha HTTP |
ITM_AUTH_URL | URL del servidor de autorización OAuth utilizada para el intercambio de tokens |
ITM_AUTH_PUBLIC_URL | URL pública de OAuth anunciada a los clientes de IA |
MCP_SERVER_URL | URL pública del servidor MCP utilizada como audiencia de OAuth |
LOG_LEVEL | Nivel de registro de Pino opcional: debug, info, warn o error |
ITM_AUDIT_ENABLED | Habilita el registro de auditoría en el servidor cuando se establece en true |
ITM_UI_URL | URL base opcional de la interfaz de ITM Platform (p. ej., https://app.itmplatform.com); cuando se establece, create_project devuelve un enlace profundo uiUrl al proyecto creado |
Cuando se implementa detrás de un proxy inverso, ITM_AUTH_URL puede apuntar a una dirección de servidor a servidor, mientras que ITM_AUTH_PUBLIC_URL debe ser accesible para los clientes de IA.
Desarrollo
Requisitos:
- Node.js 20 o posterior
- npm
Instala las dependencias, ejecuta las pruebas y compila:
npm install
npm test
npm run build
Ejecuta el servidor de desarrollo HTTP:
cp .env.sample .env
npm run dev
El punto de entrada del paquete es dist/server.js; el ejecutable de npm es mcp-server.
Solución de problemas
Si las herramientas no aparecen en tu cliente de IA, confirma que la configuración del servidor esté en el archivo correcto para ese cliente, reinicia el cliente y verifica que npx @itm-platform/mcp-server se ejecute correctamente para configuraciones locales.
Si la autenticación falla, regenera tu clave de API o vuelve a conectar el servidor OAuth para que tu cliente reciba un token nuevo.
Las sesiones de OAuth reintentan automáticamente una vez ante un 401 posterior reintercambiando el token de portador de OAuth por un token de sesión nuevo. Esto maneja los casos en los que el token de sesión se invalida externamente (p. ej., por un inicio de sesión concurrente en el navegador). Si los errores 401 persisten, es probable que el token de portador de OAuth haya caducado y el cliente de IA necesite reautenticarse.
Si una escritura se realiza correctamente pero una búsqueda posterior muestra datos antiguos, espera hasta 60 segundos. Las escrituras se confirman inmediatamente desde la API REST, mientras que los índices de búsqueda de DataMart se actualizan de forma asíncrona.
Más ayuda
- Documentación de MCP: modelcontextprotocol.io
- Ayuda de ITM Platform: helpcenter.itmplatform.com
- Documentación para desarrolladores de ITM Platform: developers.itmplatform.com