Servidor MCP

O que o servidor MCP faz

O Model Context Protocol (MCP) é uma norma aberta que permite aos assistentes de IA chamar ferramentas noutros sistemas. O servidor MCP da Nomid permite que um assistente como o claude.ai, o ChatGPT, o Claude Code, o Codex ou o Cursor responda a perguntas sobre a sua frota em linguagem natural, por exemplo, quantos dispositivos utilizam uma política ou que dispositivos não são vistos desde uma determinada data, sem que ninguém tenha de abrir o portal. Também pode diagnosticar porque é que um dispositivo não pode ser contactado remotamente, criar hiperligações para um dispositivo, política ou aplicação no portal e consultar os planos públicos e a tabela de preços da Nomid. Com uma permissão adicional, pode enviar comandos para um dispositivo de cada vez, como bloquear, reiniciar ou alterar a respetiva política, ou criar códigos QR de aprovisionamento. Uma permissão em separado autoriza comandos destrutivos, como a eliminação de dados (wipe).

Endpoint e transporte

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

O servidor utiliza o MCP Streamable HTTP em modo stateless. Cada chamada JSON-RPC é um pedido HTTPS independente, pelo que não existe nenhuma sessão para manter ativa nem qualquer fluxo de eventos para manter aberto.

Ligue-se através do Sign in with Nomid (OAuth) ou com uma chave de API. Envie uma chave de API como um token de portador (bearer) ou no cabeçalho X-API-Key. A maioria dos clientes MCP suporta apenas o formato bearer. Uma chave ou token em falta, inválido ou expirado devolve o código 401.

A chave de API ou a ligação do Sign in with Nomid define a empresa. Nenhuma ferramenta aceita um argumento de tenant ou empresa, e uma ligação só pode ver os dispositivos e as políticas da sua própria empresa.

Sign in with Nomid

Sign in with Nomid é OAuth para clientes MCP, aberto a todas as empresas. Em vez de utilizar uma chave, o utilizador inicia sessão no Nomid no navegador e aprova o que o assistente pode fazer. O assistente atua então como esse utilizador nessa empresa e apenas vê os dispositivos e políticas que a função e o acesso a políticas do utilizador permitem.

O claude.ai, o ChatGPT e o Claude Code ligam-se com Sign in with Nomid: adicione o URL do endpoint acima como um conector personalizado ou servidor MCP, sem chave, e inicie sessão quando o cliente solicitar. Os exemplos do Codex e do Cursor abaixo utilizam uma chave de API.

No Claude Code, adicione o servidor sem cabeçalho, execute /mcp no Claude Code e selecione o servidor para iniciar sessão.

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

Uma ligação inclui âmbitos de OAuth, que substituem as permissões da chave de API.

Por predefinição, os clientes solicitam mcp:read, mcp:devices:command e mcp:provisioning. O mcp:devices:destructive e o mcp:policies:write nunca são solicitados automaticamente: um cliente tem de os solicitar explicitamente.

Na página de consentimento, o utilizador pode desmarcar âmbitos, e o Nomid descarta qualquer âmbito que a função do utilizador ou as definições de acesso de agentes de IA da empresa não permitam. Aprovar um âmbito de comando, destrutivo ou de alteração de políticas requer uma sessão iniciada recentemente.

Cada pedido verifica novamente a ligação. Se o utilizador perder o acesso à empresa ou às permissões da função de que uma ferramenta necessita, ou se a empresa desativar o acesso de agentes de IA, os pedidos são recusados enquanto essa situação se mantiver.

Criar uma chave de API

O servidor MCP utiliza as mesmas chaves de API que a API REST. Crie uma chave dedicada para cada assistente para que a possa revogar sem afetar outras integrações.

1. 1

   No portal da Nomid, abra as Definições e selecione o separador API.

2. 2

   Clique em Criar chave de API e introduza um nome que identifique o assistente, por exemplo Claude Code read-only.

3. 3

   Escolha as permissões descritas abaixo. Se pretender que a chave deixe de funcionar numa determinada data, defina uma data de expiração.

4. 4

   Copie a chave quando for apresentada. Só é apresentada uma vez.

Ligar o seu assistente

Guarde a chave numa variável de ambiente denominada NOMID_API_KEY e nunca faça commit da mesma num repositório. O URL em cada exemplo é o endpoint de produção.

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}"
      }
    }
  }
}

Ferramentas disponíveis

Cada ferramenta tem como âmbito a empresa da chave ou ligação. Um dispositivo é identificado pelo seu assetId, que é o pathName devolvido por search_devices e get_device. Uma política é identificada pelo seu policyId, que é o pathName devolvido por list_policies.

Ferramentas de leitura

As ferramentas de leitura nunca alteram nada. A maioria devolve os mesmos dados que os endpoints REST correspondentes. diagnose_device, get_portal_link, search_nomid_site e o argumento query de search_devices não têm equivalente REST.

Ferramentas de comando

As ferramentas de comando atuam exatamente sobre um dispositivo físico por chamada. Não existe opção em massa. Cada ferramenta necessita de DEVICES_COMMAND e change_device_policy necessita também de POLICIES_READ.

Ferramentas de comandos destrutivos

Os clientes MCP que se ligam com Sign in with Nomid em vez de uma chave de API precisam do âmbito mcp:devices:destructive para estas ferramentas e de mcp:devices:command para as ferramentas de comando.

Que dispositivos podem receber comandos

• Apenas dispositivos inscritos podem receber comandos (estado ACTIVE, INACTIVE ou SYNCHRONIZING). Ativos eliminados, reaprovisionados e não inscritos são rejeitados.
• Alguns comandos funcionam apenas num tipo de dispositivo. Lock, lost mode, clear_app_data, reset_screen_lock e change_screen_lock_password necessitam de um dispositivo Android Management (gerido pela Google). sync_policy, shutdown_device e launch_app necessitam de um dispositivo gerido pelo agente Nomid (AOSP). Outros dispositivos recebem um erro de ferramenta.
• Uma mensagem é uma notificação push para o agente Nomid no dispositivo, pelo que o dispositivo necessita de um token de push registado.
• Um ativo pertencente a outra empresa comporta-se exatamente como um ativo que não existe.

Não disponível através de MCP ou da API REST: iniciar sessões de acesso remoto e listar ou revogar tokens de inscrição. Um código QR de aprovisionamento cria o seu próprio token de inscrição. As alterações de política têm o seu próprio fluxo de propor e aplicar.

Ferramenta de aprovisionamento

Cada chamada cria um novo token de inscrição, pelo que o assistente só deve criar um código QR quando o utilizador o solicitar, e nunca reutilizar um anterior.

O código QR é devolvido como um bloco de imagem MCP junto ao resultado em texto, para que o cliente o possa mostrar ao utilizador. O resultado em texto fornece policyId, policyName, personalUsage, expiresAt e, caso uma rede tenha sido indicada, wifiSsid. Nunca contém o token de inscrição nem a palavra-passe da rede Wi-Fi.

As ligações Sign in with Nomid necessitam do âmbito mcp:provisioning e da definição de aprovisionamento da empresa no acesso de agentes de IA. Uma chave de API com PROVISIONING não necessita dessa definição.

API de códigos QR de aprovisionamento

Segurança e auditoria

Um comando altera algo que uma pessoa tem na mão. Trate cada um como uma ação que necessita de uma decisão humana.

• Confirme sempre com o utilizador antes de qualquer comando. As descrições das ferramentas pedem ao modelo para o fazer, mas nada no servidor o impõe. Mantenha a aprovação por ferramenta do seu cliente ativada para ferramentas de comando em vez de as autoaprovar.
• Nunca reenvie um comando após um resultado não confirmado. Se o desfecho for desconhecido, verifique list_device_commands depois de o dispositivo ter tido tempo de responder e pergunte ao utilizador antes de enviar novamente. Um reenvio pode duplicar um comando que já foi entregue, e uma mensagem mostra uma segunda notificação.
• Um resultado que indique que o comando não foi enviado é seguro para tentar novamente. O comando nunca saiu do Nomid.
• Cada comando é registado no histórico de comandos do dispositivo no portal Nomid. Um comando enviado com uma chave de API é atribuído à chave, não a uma pessoa: a entrada mostra api-key, o id da chave e o prefixo da chave. Um comando enviado através de uma ligação Sign in with Nomid é atribuído ao utilizador que iniciou sessão. O histórico devolvido por list_device_commands contém apenas type, status, carimbos de data/hora e resultado, e não quem enviou o comando.
• Se um computador ou ficheiro de configuração estiver comprometido, revogue a chave em Definições, API. As chaves revogadas não podem ser restauradas. Para terminar uma ligação Sign in with Nomid, revogue-a na lista de ligações da página de agentes de IA no portal, ou desligue-a num cliente que revogue os seus tokens ao desligar. De qualquer das formas, a ligação e todos os seus tokens deixam de funcionar de imediato. Cada utilizador pode revogar as suas próprias ligações, e um utilizador que possa gerir chaves de API pode revogar qualquer ligação da empresa.

Limites de taxa

Os limites são contabilizados por chave de API ou por ligação Sign in with Nomid, em janelas fixas de um minuto. Quando excede o limite de pedidos MCP, o servidor responde com HTTP 429 Too Many Requests com um cabeçalho Retry-After que indica os segundos até ao reinício da janela.

Uma chamada da ferramenta de comando, cada chamada propose ou apply de uma ferramenta de alteração de políticas e cada chamada create_provisioning_qr_code contam para ambos os limites. Quando essa chamada excede o limite partilhado de escrita, o servidor devolve um erro da ferramenta em vez de um HTTP 429. É uma resposta normal assinalada como erro, e o respetivo texto indica quantos segundos deve aguardar. Os endpoints REST de leitura não utilizam o limite do MCP.

Resolução de problemas

Documentação relacionada

• Autenticação por chave de API
• Referência da API de comandos de dispositivos
• API de alterações de políticas
• API de códigos QR de aprovisionamento