MCP y agentes de IA

Orkestra expone ~290 herramientas MCP que cubren el 99% del backend. Cualquier cliente MCP compatible (Claude Desktop, OpenClaw, HermesAgent, etc.) puede operar Orkestra con lenguaje natural.

Transports soportados

El servidor MCP de Orkestra soporta dos transports:

  • 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.
  • Streamable HTTP (remoto) — el cliente conecta a https://mcp.orkestra.team. Útil para agentes que corren en servidores (OpenClaw, HermesAgent, N8N). Auth vía header Authorization: Bearer ork_....

Generar un token MCP

Ve a Ajustes → Tokens MCP → Crear token. Ponle un nombre descriptivo (ej: "Claude Desktop laptop Juan") para poder revocarlo después.

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).

Herramientas disponibles

Las ~290 tools están organizadas en 35 módulos. Los principales:

  • Organizations (5 tools) — listar, obtener, miembros, crear, gestionar
  • Projects (9 tools) — CRUD completo, stats, archivar/restaurar
  • Tasks (10 tools) — CRUD, mover estado, asignar, comentar, subtareas
  • Wiki (13 tools) — CRUD + versiones + comentarios
  • Workflows (5 tools) — estados, transiciones, reordenar
  • Analytics (2 tools) — métricas de proyecto, dashboard org
  • Automation (5 tools) — reglas de automatización
  • Audit (5 tools) — historial, actividad, alertas
  • Bulk (4 tools) — operaciones masivas (move, update, assign, delete)
  • Processes (5 tools) — motor de procesos con aprobaciones
  • Stock (15 tools) — inventario físico + presupuesto
  • Products (10 tools) — líneas de negocio con KPIs
  • User (2 tools + 1 resource) — perfil + contexto IA aboutMe vía orkestra://user/context
  • ...y 23 módulos más (chat, notifications, webhooks, custom fields, time tracking, etc.)

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:

  • Tool orkestra_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.

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 "pending action" con un confirmToken. Solo cuando el agente llama a confirm_action con ese token, la operación se ejecuta.

Esto evita que un agente ejecute cambios destructivos por error o por alucinación. Los clientes compatibles muestran un preview al usuario antes de confirmar.

Conectar clientes

Para guías paso a paso con configuración copiable, ve a la página completa de Agentes IA. Cubre Claude Desktop, OpenClaw y HermesAgent con ejemplos.

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). 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:

  • Billing — los cambios de plan requieren UI con confirmación humana.
  • 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