Servidor MCP

¿Qué permite hacer?

• Que un agente de IA opere ArduMaker a nombre de una persona real: proyectos, VPS, dominios, bases, correo, WordPress, deploys, túneles y más.
• Elegir al aprobar sobre qué proyectos y qué VPS puede actuar, y si es de solo lectura.
• Conectar el mismo agente a un subconjunto de herramientas (un perfil) para no gastar contexto.
• Reintentar creaciones sin duplicar nada, seguir operaciones largas y recibir errores que dicen qué hacer.

¿Cuándo conviene usarlo?

• Delegar en un agente tareas repetitivas de infraestructura o de gestión de proyectos.
• Dejar que un agente diagnostique (logs, estado) con permisos de solo lectura.
• Automatizar flujos de varios pasos (publicar un repo en un dominio, armar un túnel entre VPS) en una sola llamada.

¿Cómo funciona en ArduMaker?

Conexión y autorización

1. El cliente se registra solo en el servidor (https://mcp.ardumaker.com, registro dinámico). Registrarse no da ningún acceso.
2. El cliente abre la autorización en el navegador; ArduMaker muestra qué agente pide acceso. La solicitud vive 10 minutos y es de un solo uso.
3. La persona aprueba o rechaza y elige el alcance: todos los proyectos o algunos, todos los VPS o algunos (por separado), y si es de solo lectura.
4. El cliente recibe un access_token (8 horas) y un refresh_token (30 días, de un solo uso) y llama a las herramientas con OAuth 2.1 + PKCE.
5. Cuando vence el access token, el cliente lo renueva solo, sin volver a pedir aprobación. La sesión dura como máximo 180 días; después hay que volver a autorizar.

Cada renovación entrega un refresh token nuevo e invalida el anterior. Si llega uno ya usado, hay una copia dando vueltas: se revoca la sesión entera y se marca la conexión. Aprobar otra vez el mismo cliente reusa la conexión y abre una sesión nueva.

Descubrimiento

• Metadatos OAuth en /.well-known/oauth-authorization-server y /.well-known/oauth-protected-resource.
• /tools.json: la referencia pública de las herramientas, sin autenticación. La versión legible está en /mcp/docs.
• ping responde sin token; todo lo demás exige token.
• tools/list ya viene filtrado: un agente de solo lectura no ve las herramientas que escriben, y las de administración del sistema solo aparecen si quien autorizó es admin del sistema.

Contexto de empresa

La primera llamada recomendada es ver_contexto_inicial (también como recurso ardumaker://contexto-inicial): dice quién autorizó al agente, qué alcance tiene, hasta 50 ids de empresas, proyectos y VPS, cuántos VPS ve en total y la lista de lo que ningún agente puede hacer. Las listas están cortadas: si falta algo, se busca con listar_empresas, listar_proyectos o listar_todos_los_vps.

Lectura, escritura y acciones sensibles

• Cada herramienta declara si solo lee, si es destructiva, si es idempotente y si toca el mundo exterior. Una sin declarar se trata como de escritura.
• Las herramientas llaman a los mismos servicios que el panel web, con los permisos de la persona que autorizó: un agente nunca ve ni hace más que su humano.
• Las acciones de riesgo piden una confirmación explícita en el argumento (confirmado, confirmacion con el nombre exacto) y algunas no existen por MCP (borrar un VPS, un proyecto o un registro DNS). Ver Permisos del agente MCP.
• Lo que escribió un tercero (correos, comentarios, logs, mensajes de commit, salida de comandos) llega envuelto como {origen: "no_confiable", escrito_por, advertencia, contenido}: es dato, nunca instrucciones.

Reintentos y operaciones largas

• Toda herramienta que crea algo acepta idempotency_key. Repetir con la misma clave y los mismos argumentos devuelve el resultado original marcado idempotente: true; la clave vale 24 horas. Reusarla con otros argumentos se rechaza.
• Lo que tarda (crear un VPS, clonar un repo, activar un dominio con SSL, instalar un rol de túnel) devuelve un operacion_id. ver_operacion responde siempre igual: estado en_curso, ok o error, y reintentar_en_segundos mientras corre.
• El resultado de una operación terminada queda disponible unos días, así que tras una desconexión se recupera con ver_operacion en vez de repetir nada.

¿Qué cambia realmente?

• Al aprobar se crea una conexión entre la persona y el cliente; se ve y se administra en /me (agentes conectados).
• Cada llamada queda registrada (ver Auditoría de agentes).
• Lo que el agente modifica cambia en ArduMaker igual que si lo hiciera la persona desde el panel, y queda a nombre del agente y de quien lo autorizó.

Perfiles

Un mismo token vale en todos los perfiles: cambiar de perfil es cambiar la URL. ping, ver_contexto_inicial, ver_operacion y listar_empresas están en todos.

Límites

Algunas herramientas tienen límites propios más bajos, indicados en su descripción.

Esquema

Resultado esperado

• En el cliente aparecen las herramientas del perfil elegido, ya filtradas por el alcance.
• ver_contexto_inicial confirma a nombre de quién actúa el agente y qué puede hacer.
• En /me se ve la conexión: activa o no, último uso, hasta cuándo dura la sesión y qué está haciendo el agente.

Errores y resolución

Todo error llega con la misma forma, sin trazas internas:

{
  "error": true,
  "code": "parametro_invalido",
  "que_paso": "...",
  "que_hacer": "...",
  "reintentable": false,
  "detalle": { "fields": { "...": "..." } }
}

• reintentable: true significa que repetir la MISMA llamada, sin cambiar nada, puede funcionar.
• En OAuth, invalid_grant con Refresh token already used; the session was revoked indica reutilización detectada: hay que volver a autorizar.
• Un timeout de un comando (agente_timeout) no significa que no corrió: conviene revisar antes de repetirlo.

Relación con MCP

Este documento es el propio servidor MCP. La referencia de cada herramienta (parámetros, si lee o escribe, si es destructiva) está en /mcp/docs, y la presentación con ejemplos por área en /mcp.

• Herramientas comunes: ping (sin autenticación), ver_contexto_inicial, listar_empresas, ver_operacion.
• Para instalar algo en un VPS, el orden recomendado es: instalar_app para lo que ofrece el catálogo; la configuración de deploy (guardar_config_deploy_app) para los procesos de una app de Git; crear_servicio_vps y crear_tarea_vps para lo demás; ejecutar_comando_vps solo si nada de lo anterior sirve.

Funciones relacionadas

• Permisos del agente MCP
• Auditoría de agentes
• Claves de IA
• Servidores VPS
• Proyectos y tablero kanban