MCP y agentes de IA

Orkestra expone un servidor MCP que cubre el 99% del backend con 29 herramientas de dominio (~296 acciones). 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 29 herramientas de dominio. Cada una acepta un parámetro action que abre las ~296 acciones del backend, 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 (hasta 4× menos contexto en el cliente que un tool por acción). Algunos dominios:

  • orkestra_tasks, orkestra_projects, orkestra_wiki — tareas, proyectos y wiki
  • orkestra_organizations, orkestra_areas — organizaciones, áreas y organigrama
  • orkestra_sprints, orkestra_time, orkestra_planning — sprints, time tracking y planificación
  • orkestra_analytics, orkestra_finance, orkestra_stock — analytics y reportes, finanzas, inventario
  • productos, portfolio y goals; admin (RBAC, audit, automatización); integraciones; plantillas
  • procesos y check-ins; helpdesk; portal de cliente; operaciones masivas (bulk)
  • usuario y actividades; custom fields; workflows de IA; chat; notificaciones; data tables; OrgOS
  • más las tools discretas de search y de confirmación (orkestra_confirm_action)

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 los clientes compatibles (Claude Desktop, entre otros) pueden cargar automáticamente al iniciar una sesió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 que los clientes compatibles pueden cargar automáticamente:

  • 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 sprint, Triaje de backlog, 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