Servidor MCP

Qué hace el servidor MCP

El Model Context Protocol (MCP) es un estándar abierto que permite a los asistentes de IA invocar herramientas en otros sistemas. El servidor MCP de Nomid permite a un asistente como claude.ai, ChatGPT, Claude Code, Codex o Cursor responder preguntas sobre su flota en lenguaje natural, por ejemplo cuántos dispositivos usan una política o qué dispositivos no se han visto desde una fecha determinada, sin necesidad de que nadie abra el portal. También puede diagnosticar por qué no se puede establecer comunicación remota con un dispositivo, enlazar a un dispositivo, política o aplicación en el portal, y consultar los planes públicos y precios de lista de Nomid. Con un permiso adicional puede enviar comandos a un dispositivo a la vez, como bloquear, reiniciar o cambiar su política, o crear códigos QR de aprovisionamiento. Un permiso independiente permite comandos destructivos como el borrado remoto.

Endpoint y transporte

POST https://api.nomid.tech/emm/api/mcp

El servidor utiliza MCP Streamable HTTP en modo sin estado. Cada llamada JSON-RPC es una solicitud HTTPS independiente, por lo que no hay ninguna sesión que mantener activa ni ningún flujo de eventos que mantener abierto.

Conéctese con Sign in with Nomid (OAuth) o con una clave de API. Envíe una clave de API como token bearer o en el encabezado X-API-Key. La mayoría de los clientes MCP solo admiten el formato bearer. Si la clave o el token faltan, son inválidos o han caducado, se devuelve un error 401.

La clave de API o la conexión de Sign in with Nomid determina la empresa. Ninguna herramienta acepta un argumento de inquilino o empresa, y una conexión solo puede ver los dispositivos y las políticas de su propia empresa.

Sign in with Nomid

Sign in with Nomid es OAuth para clientes MCP, abierto a todas las empresas. En lugar de usar una clave, el usuario inicia sesión en Nomid en el navegador y aprueba lo que el asistente puede hacer. Luego, el asistente actúa como ese usuario en esa empresa, y solo ve los dispositivos y las políticas que el rol y el acceso a políticas del usuario permiten.

claude.ai, ChatGPT y Claude Code se conectan con Sign in with Nomid: agregue la URL de endpoint anterior como un conector personalizado o servidor MCP, sin una clave, e inicie sesión cuando el cliente lo solicite. Los ejemplos de Codex y Cursor a continuación usan una clave de API.

En Claude Code, agregue el servidor sin encabezado, luego ejecute /mcp en Claude Code y seleccione el servidor para iniciar sesión.

claude mcp add --transport http nomid-mdm https://api.nomid.tech/emm/api/mcp

Una conexión incluye ámbitos (scopes) de OAuth, que reemplazan los permisos de clave de API.

Los clientes solicitan mcp:read, mcp:devices:command y mcp:provisioning de forma predeterminada. mcp:devices:destructive y mcp:policies:write nunca se solicitan automáticamente: un cliente debe solicitarlos explícitamente.

En la página de consentimiento, el usuario puede desmarcar ámbitos, y Nomid descarta cualquier ámbito que el rol del usuario o la configuración de acceso de agentes de IA de la empresa no permitan. Aprobar un ámbito de comandos, destructivo o de cambio de políticas requiere un inicio de sesión reciente.

Cada solicitud verifica la conexión nuevamente. Si el usuario pierde el acceso a la empresa o los permisos de rol que necesita una herramienta, o si la empresa desactiva el acceso de agentes de IA, las solicitudes se rechazan mientras eso persista.

Crear una clave de API

El servidor MCP utiliza las mismas claves de API que la API REST. Cree una clave dedicada para cada asistente para poder revocarla sin afectar a otras integraciones.

1. 1

   En el portal de Nomid, abra Configuración y seleccione la pestaña API.

2. 2

   Haga clic en Crear clave de API e ingrese un nombre que identifique al asistente, por ejemplo Claude Code solo lectura.

3. 3

   Elija los permisos descritos a continuación. Si desea que la clave deje de funcionar en una fecha determinada, establezca una fecha de caducidad.

4. 4

   Copie la clave cuando se muestre. Solo se muestra una vez.

Conecte su asistente

Guarde la clave en una variable de entorno llamada NOMID_API_KEY y nunca la confirme en un repositorio. La URL en cada ejemplo es el endpoint de producción.

claude mcp add --transport http nomid-mdm https://api.nomid.tech/emm/api/mcp \
  --header "Authorization: Bearer ${NOMID_API_KEY}"

[mcp_servers.nomid]
url = "https://api.nomid.tech/emm/api/mcp"
bearer_token_env_var = "NOMID_API_KEY"

{
  "mcpServers": {
    "nomid-mdm": {
      "url": "https://api.nomid.tech/emm/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:NOMID_API_KEY}"
      }
    }
  }
}

Herramientas disponibles

Cada herramienta se limita al ámbito de la empresa de la clave o conexión. Un dispositivo se identifica mediante su assetId, que es el pathName devuelto por search_devices y get_device. Una política se identifica mediante su policyId, que es el pathName devuelto por list_policies.

Herramientas de lectura

Las herramientas de lectura nunca modifican nada. La mayoría devuelve los mismos datos que los endpoints REST correspondientes. diagnose_device, get_portal_link, search_nomid_site y el argumento query de search_devices no tienen equivalente REST.

Herramientas de comandos

Las herramientas de comandos actúan exactamente sobre un dispositivo físico por llamada. No existe una opción masiva o por lotes. Cada herramienta necesita DEVICES_COMMAND, y change_device_policy también necesita POLICIES_READ.

Herramientas de comandos destructivos

Los clientes MCP que se conectan con Sign in with Nomid en lugar de una clave API necesitan el ámbito mcp:devices:destructive para estas herramientas, y mcp:devices:command para las herramientas de comando.

Qué dispositivos pueden recibir comandos

• Solo los dispositivos inscritos pueden recibir comandos (estado ACTIVE, INACTIVE o SYNCHRONIZING). Los activos eliminados, reprovisionados y dados de baja son rechazados.
• Algunos comandos solo funcionan en un tipo de dispositivo. Lock, lost mode, clear_app_data, reset_screen_lock y change_screen_lock_password necesitan un dispositivo Android Management (administrado por Google). sync_policy, shutdown_device y launch_app necesitan un dispositivo administrado por el agente Nomid (AOSP). Otros dispositivos reciben un error de herramienta.
• Un mensaje es una notificación push dirigida al agente Nomid en el dispositivo, por lo que el dispositivo necesita un token push registrado.
• Un activo que pertenece a otra empresa se comporta exactamente igual que un activo que no existe.

No disponible a través de MCP ni de la API REST: iniciar sesiones de acceso remoto y listar o revocar tokens de inscripción. Un código QR de aprovisionamiento crea su propio token de inscripción. Los cambios de política tienen su propio flujo de propuesta y aplicación.

Herramienta de aprovisionamiento

Cada llamada crea un nuevo token de inscripción, por lo que el asistente debe crear un código QR solo cuando el usuario lo solicite, y nunca reutilizar uno anterior.

El código QR se devuelve como un bloque de imagen MCP junto al resultado de texto, para que el cliente pueda mostrárselo al usuario. El resultado de texto proporciona policyId, policyName, personalUsage, expiresAt y, cuando se proporcionó una red, wifiSsid. Nunca contiene el token de inscripción ni la contraseña de Wi-Fi.

Las conexiones de Sign in with Nomid necesitan el ámbito mcp:provisioning y la configuración de aprovisionamiento de la empresa bajo el acceso de agentes de IA. Una clave de API con PROVISIONING no necesita esa configuración.

API de códigos QR de aprovisionamiento

Seguridad y auditoría

Un comando cambia algo que una persona tiene en sus manos. Trata cada uno como una acción que requiere una decisión humana.

• Confirma siempre con el usuario antes de cualquier comando. Las descripciones de las herramientas le piden al modelo que haga esto, pero nada en el servidor lo impone. Mantén activada la aprobación por herramienta en tu cliente para las herramientas de comandos en lugar de aprobarlas automáticamente.
• Nunca reenvíes un comando tras un resultado no confirmado. Si se desconoce el resultado, consulta list_device_commands después de que el dispositivo haya tenido tiempo de responder y pregunta al usuario antes de enviarlo de nuevo. Un reenvío puede duplicar un comando que ya se entregó, y un mensaje muestra una segunda notificación.
• Es seguro reintentar si el resultado indica que el comando no se envió. El comando nunca salió de Nomid.
• Cada comando se registra en el historial de comandos del dispositivo en el portal de Nomid. Un comando enviado con una clave de API se atribuye a la clave, no a una persona: la entrada muestra api-key, el id de la clave y el prefijo de la clave. Un comando enviado a través de una conexión de Sign in with Nomid se atribuye al usuario que inició sesión. El historial que devuelve list_device_commands contiene únicamente el tipo, el estado, las marcas de tiempo y el resultado, no quién envió el comando.
• Si un equipo o un archivo de configuración se ven comprometidos, revoca la clave desde Configuración, API. Las claves revocadas no se pueden restaurar. Para finalizar una conexión de Sign in with Nomid, revócala en la lista de conexiones de la página de agentes de IA en el portal, o desconéctala en un cliente que revoque sus tokens al desconectarse. De cualquier manera, la conexión y todos sus tokens dejan de funcionar de inmediato. Cada usuario puede revocar sus propias conexiones, y un usuario que pueda administrar claves de API puede revocar cualquier conexión de la empresa.

Límites de frecuencia

Los límites se calculan por clave de API o por conexión de Sign in with Nomid, en ventanas fijas de un minuto. Cuando se supera el límite de solicitudes de MCP, el servidor responde HTTP 429 Too Many Requests con un encabezado Retry-After que indica los segundos que faltan para que se restablezca la ventana.

Una llamada a una herramienta de comandos, cada llamada propose o apply de una herramienta de cambio de políticas y cada llamada a create_provisioning_qr_code cuentan para ambos límites. Cuando dicha llamada supera el límite de escritura compartido, el servidor devuelve un error de herramienta en lugar de un HTTP 429. Se trata de una respuesta normal marcada como error, y su texto indica cuántos segundos se debe esperar. Los endpoints de lectura REST no utilizan el límite MCP.

Resolución de problemas

Documentación relacionada

• Autenticación con clave API
• Referencia de la API de comandos de dispositivos
• API de cambios de políticas
• API de códigos QR de aprovisionamiento