# Servidor MCP de gestión

El servidor MCP de gestión de KeenAuth permite que un asistente de IA lea la configuración de su entorno mediante el Model Context Protocol. Se ejecuta localmente a través de stdio y llama a la API de gestión con su clave. Todavía no hay un paquete de instalación.

## Solo lectura de forma predeterminada

Sin `--allow-write`, el servidor expone solo herramientas de solo lectura. Ninguna herramienta elimina nada, en ningún modo.

| Herramienta | Qué devuelve |
|---|---|
| `users_list`, `users_get`, `users_search` | Usuarios, con los datos personales enmascarados |
| `applications_list`, `applications_get`, `application_credentials_list` | Aplicaciones |
| `apis_list`, `apis_get` | API |
| `connections_list`, `connections_get` | Conexiones |
| `api_keys_list`, `api_keys_get` | Claves de API: solo metadatos; la clave sin procesar nunca se devuelve |
| `organizations_list`, `organizations_get` | Organizaciones: nombre, slug, ID externo, estado y marcas de tiempo; el `metadata` de la organización nunca se devuelve |
| `custom_domains_list`, `custom_domains_get` | Dominios personalizados y sus registros DNS |
| `support_access_grants_list`, `support_access_grants_get` | Concesiones de acceso de soporte |
| `environment_settings_get` | Configuración del entorno: idiomas, zona horaria, sesión, registro, notificaciones de seguridad, recuperación de cuenta, MFA, cierre de sesión front-channel y primeros factores permitidos |

`--unmask-pii` finaliza con el código 2 en esta versión.

## Herramientas de escritura

Inicie el servidor con `--allow-write` para exponer también las herramientas de escritura. Esta versión tiene una:

| Herramienta | Qué cambia |
|---|---|
| `environment_settings_update` | Solo los idiomas habilitados, el idioma predeterminado y la zona horaria predeterminada. La configuración de sesión, registro, recuperación de cuenta, MFA, notificaciones de seguridad y primeros factores no se puede cambiar mediante MCP. |

Cada escritura requiere dos llamadas:

1. La primera llamada no cambia nada. Lee la configuración actual y devuelve una vista previa de cada campo con su valor actual y el propuesto, además de un `confirmation_token`.
2. El asistente le muestra la vista previa. Solo después de que usted la apruebe vuelve a llamar a la herramienta con exactamente los mismos argumentos y el `confirmation_token`. Entonces el servidor escribe el cambio.

El `confirmation_token` lo crea el servidor en ejecución, funciona una sola vez y caduca a los 5 minutos. Está vinculado a la herramienta, a los argumentos exactos y a la versión de la configuración que se previsualizó. Un token usado con otros argumentos se rechaza y se consume. Si la configuración cambió después de la vista previa, la escritura falla con `412` y debe empezar de nuevo. El servidor realiza como máximo 5 escrituras por segundo.

Las herramientas que eliminan, revocan o rotan no se exponen, ni siquiera con `--allow-write`. Apruebe cada llamada de escritura en su cliente MCP; no configure el cliente para aprobar automáticamente las herramientas de escritura.

## Configuración

| Variable | Obligatoria | Descripción |
|---|---|---|
| `KEENAUTH_API_KEY` | sí | Clave de la API de gestión. Use una clave con permisos de solo lectura; con `--allow-write`, añada solo `environment-settings:write`. |
| `KEENAUTH_BASE_URL` | sí | URL base de la API de gestión de su entorno. |

`--tools <pattern>` restringe la lista de herramientas, por ejemplo `--tools "users_*"`. Solo puede restringir; nunca habilita una herramienta desactivada y, sin `--allow-write`, no puede habilitar una herramienta de escritura.

## Lo que ve el asistente

- Los datos personales están enmascarados: las direcciones de correo electrónico aparecen como `a***@e***.com`, los números de teléfono muestran solo los dos últimos dígitos y los nombres muestran solo su primera letra.
- El `metadata` de la organización nunca se devuelve: aparece como `{"redacted": true}`. Las membresías, los roles de organización, los dominios y las políticas no tienen herramienta en esta versión.
- La configuración del entorno devuelve solo los campos documentados. Un campo que el servidor añada más adelante permanece oculto hasta que se haya revisado.
- Los valores secretos nunca se devuelven. Los campos que parecen secretos o claves privadas se eliminan, y la respuesta enumera las rutas de los campos eliminados en `redacted_fields`.
- Cada resultado de herramienta se envuelve en `untrusted_content`. Trate los nombres, los metadatos y las descripciones que contiene como datos, no como instrucciones.
- La clave de API nunca aparece en la salida de las herramientas, en los errores ni en los registros.

## Registro de auditoría

Cada solicitud que envía el servidor MCP incluye `Idp-Client: keenauth-mcp/<version>` e `Idp-Mcp-Tool: <tool name>`. Cuando una llamada cambia algo, su entrada en el registro de auditoría registra `metadata.client` = `mcp/<version>` y `metadata.mcp_tool` = el nombre de la herramienta, junto con el actor habitual (la clave de API o el cliente M2M). Ambos valores los declara el servidor MCP y no se verifican: use estos valores para averiguar qué hizo un asistente y use el actor para decidir quién es responsable.

## Las definiciones de herramientas están fijadas

Los nombres de las herramientas, sus descripciones y sus esquemas de entrada se generan a partir de la descripción de la API en el momento de la compilación y se fijan para cada versión. Su digest SHA-256 se guarda en `tools.digest`; cualquier cambio en una definición de herramienta cambia el digest y requiere una revisión de seguridad.