MCP y agentes de IA

Orkestra expone un servidor MCP que cubre casi todo el backend con una herramienta por dominio. claude.ai y ChatGPT se conectan con OAuth 2.1 pegando una sola URL — sin copiar tokens. Cualquier otro cliente MCP compatible puede operar Orkestra con lenguaje natural.

Conectar con OAuth (recomendado)

Para claude.ai y ChatGPT no hace falta copiar ningún token: se conectan con OAuth 2.1 pegando la URL https://mcp.orkestra.team/mcp.

  • claude.ai — Ajustes → Conectores → Añadir conector personalizado → pega la URL → inicia sesión y acepta el consentimiento en Orkestra.
  • ChatGPT — conectores en modo desarrollador, misma URL.
  • Claude Code (terminal) — claude mcp add --transport http orkestra https://mcp.orkestra.team/mcp (OAuth se abre en el navegador).

Las reconexiones son silenciosas: una vez aprobado, no se vuelve a pedir consentimiento. La guía interactiva dentro de la app vive en Conectar tu IA.

Transports soportados

El servidor MCP de Orkestra soporta dos transports:

  • Streamable HTTP (remoto) — el cliente conecta a https://mcp.orkestra.team/mcp. Es el camino de claude.ai, ChatGPT y Claude Code (OAuth), y también sirve para clientes HTTP propios (N8N, scripts) vía header Authorization: Bearer ork_....
  • STDIO (local) — el cliente arranca el servidor como un subprocess. Útil para Claude Desktop, donde el MCP corre junto al cliente. Auth vía env var MCP_TOKEN.

Generar un token MCP

Los tokens siguen existiendo para clientes locales por STDIO o clientes HTTP propios (N8N, scripts, tu agente). Ve a Ajustes → Tokens MCP → Crear token. Ponle un nombre descriptivo (ej: “Claude Desktop laptop Juan”) y elige el nivel de acceso: total o solo lectura (un token de solo lectura solo puede llamar tools de lectura).

El valor del token se muestra una sola vez. Cópialo y guárdalo en un gestor de contraseñas. Si lo pierdes, hay que crear uno nuevo (y revocar el anterior). Revocar un token también desconecta a los clientes OAuth asociados.

Herramientas disponibles

En lugar de un tool por acción, Orkestra expone una herramienta por dominio. Cada una acepta un parámetro action que abre las acciones de ese dominio, y con action: "describe" el agente pide el esquema completo de una acción solo cuando lo necesita. Así la lista de tools se mantiene pequeña. Algunos dominios:

  • orkestra_tasks, orkestra_projects, orkestra_wiki — tareas, proyectos y documentos
  • orkestra_organizations, orkestra_areas — organizaciones, áreas y organigrama
  • orkestra_sprints, orkestra_time, orkestra_planning — ciclos, tiempos y planificación
  • orkestra_analytics, orkestra_finance, orkestra_stock — analytics y reportes, finanzas, inventario
  • productos y metas; admin (roles, auditoría, automatización); integraciones; plantillas
  • check-ins; helpdesk; portal de cliente; operaciones masivas (bulk)
  • usuario y actividades; campos personalizados; chat; notificaciones; tablas de datos; OrgOS
  • más las tools discretas orkestra_overview (qué es Orkestra, cómo se encadenan los dominios y tus organizaciones: lo primero que un agente llama en una conversación sin contexto), orkestra_search, orkestra_help y la de confirmación (orkestra_confirm_action)

Cada dato en su registro

Un agente tiende a “anotar”: pedirle que la tarea del baño necesita tres cajas de tornillos y verlo escribir un comentario. Ese comentario es texto que nadie suma, compra ni descuenta. Por eso el servidor no acepta prosa donde hay un registro: un comentario, una descripción o un mensaje de chat que lea como un insumo con cantidad, dinero, horas trabajadas, una decisión, una dependencia, una fecha límite, un responsable o un estado se rechaza, y la respuesta nombra la acción que lo registra (request_stock, create_expense, log_time, capture_decision, assign_task…). Si de verdad es prosa sobre el tema y no el dato en sí, el agente repite la llamada con prose_intended: true y el texto se escribe igual.

Al leer una tarea, el agente también recibe los datos que su descripción o sus comentarios ya traen como texto, con la acción que los registra, para que pueda ofrecerte pasarlos a su lugar. En Ajustes → Conectar IA ves cuántas veces tu IA insistió con prose_intended: vale la pena mirar dónde quedó eso.

Contexto personal del usuario

Cada usuario puede completar un campo libre de hasta 2000 caracteres en su perfil (Ajustes → Contexto para IA) describiendo su rol, experiencia, preferencias de comunicación, zona horaria, etc. El MCP lo expone de dos formas para que los agentes lo consuman sin que tengas que repetirte en cada sesión:

  • Acción orkestra_user → get_profile — devuelve el campo aboutMe envuelto en <user_context>...</user_context> junto con una instrucción explícita al agente para que trate el contenido como datos, no como instrucciones (defensa contra prompt-injection).
  • Resource orkestra://user/context — recurso MCP que el cliente muestra para que lo adjuntes a una conversación, inyectando el contexto en el system prompt del agente.

El valor se sanitiza server-side (strip de caracteres de control + normalización Unicode NFC + trim) antes de almacenarse, y solo se devuelve en endpoints del propio usuario (/users/me) — nunca se expone a otros miembros de la organización.

Recursos y prompts

Además del contexto de usuario, el servidor expone recursos. Ningún conector actual los lee por su cuenta: claude.ai, ChatGPT y Claude Code los muestran para que los adjuntes a mano cuando los quieras en contexto.

  • orkestra://user/myday — tareas asignadas vencidas y próximas + actividades programadas.
  • orkestra://user/organizations — mapa de organizaciones y proyectos con sus IDs.
  • orkestra://user/context — el contexto para IA (aboutMe) del usuario.
  • orkestra://org/{orgId}/world-model — OrgOS: DRIs, decisiones y brechas.
  • orkestra://org/{orgId}/structure — áreas y organigrama.

El servidor también incluye 5 prompts en español que los clientes compatibles muestran como comandos: Resumen semanal, Planificar un ciclo, Triaje de pendientes, Mi día y Reporte de estado de proyecto.

Preview / confirm automático

Todas las operaciones de escritura pasan por un flujo de preview/confirm. Cuando un agente pide crear, actualizar o eliminar algo, la respuesta es un preview con un actionId. Solo cuando el agente llama a la tool orkestra_confirm_action con ese actionId, la operación se ejecuta.

En clientes STDIO que soportan elicitation de MCP (Claude Desktop, Claude Code) la confirmación aparece como un diálogo nativo en lugar del flujo de dos pasos. Esto evita que un agente ejecute cambios destructivos por error o por alucinación. Límite: 30 confirmaciones por minuto por usuario.

Tiempo real

Los cambios hechos vía MCP se propagan en vivo: la web se actualiza vía Socket.io y los webhooks, la integración con Slack y las reglas de automatización se disparan igual que si el cambio viniera de la app (bridge de eventos sobre Redis).

Conectar clientes

Para guías paso a paso con configuración copiable, ve a la página completa de Agentes IA. Cubre la conexión OAuth de claude.ai y ChatGPT, Claude Code y los clientes locales/personalizados con token.

Límites y rate limiting

El servidor MCP respeta los mismos rate limits que la API REST: 1000 requests por minuto por token en operaciones normales, 100/minuto en operaciones de escritura sensibles (bulk, custom roles, webhooks), y 30 confirmaciones por minuto por usuario. Si ves 429, espera y reintenta con backoff exponencial.

Qué NO está en MCP (por diseño)

Algunas operaciones están excluidas del MCP a propósito:

  • Gestión de tokens MCP — evitar loops circulares (un token no puede crear tokens).
  • Calendar sync OAuth — requiere redirección del usuario.
  • Export/Import con archivos — el transport MCP no maneja bien binarios grandes.

Recursos