# Servidor MCP

Servidor MCP con OAuth y aprobación humana para que agentes de IA operen ArduMaker, con perfiles, reintentos seguros y límites.

Fuente: https://ardumaker.com/docs/servidor-mcp/

- Categoría: Inteligencia artificial y agentes
- Estado: Disponible
- Requisitos: Una cuenta de ArduMaker para aprobar el acceso del agente; Un cliente compatible con MCP y OAuth (por ejemplo Claude, ChatGPT o Cursor); Acceso, como persona, a las empresas, proyectos y VPS que el agente va a usar
- Herramientas MCP (Solo leen): `ping`, `ver_contexto_inicial`, `listar_empresas`, `ver_operacion`

## ¿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](https://ardumaker.com/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](https://ardumaker.com/docs/permisos-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](https://ardumaker.com/docs/auditoria-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

| Ruta | Qué sirve |
| --- | --- |
| `/mcp` | Todo; no cambia nunca |
| `/mcp/vps` | VPS, dominios y nginx, usuarios Linux, systemd, tareas, bases, deploys, túneles, logs y Apps |
| `/mcp/proyectos` | Proyectos, etapas, tareas, checklists, comentarios, adjuntos, calendario, reuniones y papelera |
| `/mcp/infra` | Correo, dominios y DNS, blogs, estado de cobro, claves de RouterIA y Search API, sandbox y webhooks de WhatsApp |
| `/mcp/wordpress` | Sitios WordPress, WooCommerce y Elementor, más `instalar_app` y `listar_vps` |

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

| Límite | Valor | Qué pasa al pasarlo |
| --- | --- | --- |
| Llamadas por conexión | 10 por segundo | `limite_excedido` con `reintentar_en_segundos`; el rechazo no gasta cupo |
| Listas en una respuesta | 200 elementos | Se recorta y se agrega `<clave>_recortado` con el total real |
| `limit` fuera de rango | El máximo de cada herramienta | Se ajusta y se avisa en `limit_ajustado` |
| Comandos en un VPS | 10 por segundo por VPS; salida de 20000 caracteres; espera de 10 a 300 s | Rechazo o salida truncada (`truncated: true`) |
| Cambios DNS | 10 por minuto por empresa | 429 |
| Copias de VPS a mano | 1 por hora por VPS | 429 |

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

## Esquema

**Una llamada a una herramienta**

```text
Cliente MCP (token Bearer de la sesión)
  ↓
Auditoría (envuelve todo: también los rechazos quedan registrados)
  ↓
Límite por conexión (10 llamadas por segundo)
  ↓
Guardas (solo lectura, admin del sistema, idempotencia)
  ↓
Herramienta (mismo servicio que el panel, con el alcance en vivo)
  ↓
Respuesta (datos, o error estructurado)
```

## 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:

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

| `code` | Significa | ¿Reintentable? |
| --- | --- | --- |
| `no_encontrado` | El id no existe; puede traer `candidatos` válidos | No |
| `sin_permiso` | La persona, el alcance o la regla de MCP no lo permiten | No |
| `parametro_invalido` | Un argumento está mal; `detalle` dice cuál | No |
| `conflicto` | Hace falta cambiar un argumento (por ejemplo, confirmar) | No |
| `estado_invalido` | El mundo no está listo: VPS apagado, servicio externo caído | Sí |
| `limite_excedido` | Se pasó un límite; esperar `reintentar_en_segundos` | Sí |
| `interno` | Error inesperado; trae `correlacion_id` para reportarlo | Sí, una vez |

- `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](https://ardumaker.com/mcp/docs), y la presentación con ejemplos por área en [/mcp](https://ardumaker.com/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](https://ardumaker.com/docs/permisos-mcp/)
- [Auditoría de agentes](https://ardumaker.com/docs/auditoria-de-agentes/)
- [Claves de IA](https://ardumaker.com/docs/claves-ia/)
- [Servidores VPS](https://ardumaker.com/docs/vps/)
- [Proyectos y tablero kanban](https://ardumaker.com/docs/proyectos-kanban/)