Servidor MCP

O que o servidor MCP faz

O Model Context Protocol (MCP) é um padrão aberto que permite que assistentes de IA chamem ferramentas em outros sistemas. O servidor MCP da Nomid permite que um assistente como claude.ai, ChatGPT, Claude Code, Codex ou Cursor responda a perguntas sobre sua frota em linguagem natural — por exemplo, quantos dispositivos usam uma política ou quais dispositivos não são vistos desde uma determinada data —, sem que ninguém precise abrir o portal. Ele também pode diagnosticar por que um dispositivo não pode ser acessado remotamente, fornecer links para um dispositivo, política ou aplicativo no portal e consultar os planos públicos e a tabela de preços da Nomid. Com uma permissão adicional, ele pode enviar comandos para um dispositivo por vez, como bloquear, reiniciar ou alterar sua política, ou criar códigos QR de provisionamento. Uma permissão separada autoriza comandos destrutivos, como wipe (limpeza remota).

Endpoint e transporte

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

O servidor usa MCP Streamable HTTP no modo stateless. Cada chamada JSON-RPC é uma requisição HTTPS independente, portanto não há sessão para manter ativa nem fluxo de eventos para manter aberto.

Conecte-se com o Sign in with Nomid (OAuth) ou com uma chave de API. Envie uma chave de API como um bearer token ou no cabeçalho X-API-Key. A maioria dos clientes MCP suporta apenas o formato bearer. Uma chave ou token ausente, inválido ou expirado retorna 401.

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

Sign in with Nomid

Sign in with Nomid é o OAuth para clientes MCP, aberto a todas as empresas. Em vez de usar uma chave, o usuário faz login no Nomid no navegador e aprova o que o assistente pode fazer. O assistente então atua como esse usuário nessa empresa e visualiza apenas os dispositivos e políticas que a função do usuário e o acesso a políticas permitem.

O claude.ai, o ChatGPT e o Claude Code conectam-se com Sign in with Nomid: adicione o URL do endpoint acima como um conector personalizado ou servidor MCP, sem chave, e faça login quando o cliente solicitar. Os exemplos do Codex e do Cursor abaixo usam uma chave de API.

No Claude Code, adicione o servidor sem um cabeçalho, depois execute /mcp no Claude Code e selecione o servidor para fazer login.

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

Uma conexão carrega escopos OAuth, que substituem as permissões da chave de API.

Os clientes solicitam mcp:read, mcp:devices:command e mcp:provisioning por padrão. mcp:devices:destructive e mcp:policies:write nunca são solicitados automaticamente: o cliente precisa solicitá-los explicitamente.

Na página de consentimento, o usuário pode desmarcar escopos, e o Nomid descarta qualquer escopo que a função do usuário ou as configurações de acesso do agente de IA da empresa não permitam. Aprovar um escopo de comando, destrutivo ou de alteração de política exige um login recente.

Cada solicitação verifica a conexão novamente. Se o usuário perder o acesso à empresa ou às permissões de função necessárias para uma ferramenta, ou se a empresa desativar o acesso do agente de IA, as solicitações serão recusadas enquanto durar essa condição.

Criar uma chave de API

O servidor MCP usa as mesmas chaves de API que a API REST. Crie uma chave dedicada para cada assistente para poder revogá-la sem afetar outras integrações.

1. 1

   No portal da Nomid, abra Configurações e selecione a aba API.

2. 2

   Clique em Criar chave de API e insira um nome que identifique o assistente, por exemplo, Claude Code somente leitura.

3. 3

   Escolha as permissões descritas abaixo. Se quiser que a chave pare de funcionar em uma data específica, defina uma data de expiração.

4. 4

   Copie a chave quando ela for exibida. Ela é mostrada apenas uma vez.

Conecte seu assistente

Armazene a chave em uma variável de ambiente chamada NOMID_API_KEY e nunca faça commit dela em um repositório. A 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 é limitada ao escopo da empresa da chave ou conexão. Um dispositivo é identificado pelo seu assetId, que é o pathName retornado por search_devices e get_device. Uma política é identificada pelo seu policyId, que é o pathName retornado por list_policies.

Ferramentas de leitura

Ferramentas de leitura nunca alteram nada. A maioria retorna 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

Ferramentas de comando atuam em exatamente um dispositivo físico por chamada. Não há opção em lote. Cada ferramenta precisa de DEVICES_COMMAND, e change_device_policy também precisa de POLICIES_READ.

Ferramentas de comando destrutivo

Clientes MCP que se conectam com o Sign in with Nomid em vez de uma chave de API precisam do escopo mcp:devices:destructive para essas ferramentas, e mcp:devices:command para as ferramentas de comando.

Quais dispositivos podem receber comandos

• Apenas dispositivos inscritos podem receber comandos (status ACTIVE, INACTIVE ou SYNCHRONIZING). Ativos excluídos, reprovisionados e desinscritos são rejeitados.
• Alguns comandos funcionam apenas em um tipo de dispositivo. Lock, lost mode, clear_app_data, reset_screen_lock e change_screen_lock_password precisam de um dispositivo Android Management (gerenciado pelo Google). sync_policy, shutdown_device e launch_app precisam de um dispositivo gerenciado pelo agente Nomid (AOSP). Outros dispositivos recebem um erro de ferramenta.
• Uma mensagem é uma notificação push para o agente Nomid no dispositivo, portanto o dispositivo precisa de um token push registrado.
• Um ativo que pertence a outra empresa se comporta exatamente como um ativo que não existe.

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

Ferramenta de provisionamento

Cada chamada cria um novo token de registro, portanto o assistente deve criar um código QR apenas quando o usuário solicitar um, e nunca reutilizar um antigo.

O código QR é retornado como um bloco de imagem MCP ao lado do resultado em texto, para que o cliente possa mostrá-lo ao usuário. O resultado em texto informa policyId, policyName, personalUsage, expiresAt e, quando uma rede tiver sido informada, wifiSsid. Ele nunca contém o token de registro ou a senha do Wi-Fi.

As conexões do Sign in with Nomid precisam do escopo mcp:provisioning e da configuração de provisionamento da empresa em acesso do agente de IA. Uma chave de API com PROVISIONING não precisa dessa configuração.

API de códigos QR de provisionamento

Segurança e auditoria

Um comando altera algo que uma pessoa está segurando. Trate cada um como uma ação que precisa de uma decisão humana.

• Sempre confirme com o usuário antes de qualquer comando. As descrições das ferramentas pedem ao modelo para fazer isso, mas nada no servidor força essa ação. Mantenha a aprovação por ferramenta do seu cliente ativada para ferramentas de comando em vez de aprová-las automaticamente.
• Nunca reenvie um comando após um resultado não confirmado. Se o resultado for desconhecido, verifique list_device_commands depois que o dispositivo tiver tido tempo de responder e pergunte ao usuário antes de enviar novamente. Um reenvio pode duplicar um comando que já foi entregue, e uma mensagem exibe uma segunda notificação.
• Um resultado que diz que o comando não foi enviado é seguro para tentar novamente. O comando nunca saiu do Nomid.
• Cada comando é registrado 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 por meio de uma conexão Sign in with Nomid é atribuído ao usuário que fez login. O histórico retornado por list_device_commands contém apenas tipo, status, carimbos de data/hora e resultado, não quem enviou o comando.
• Se um computador ou arquivo de configuração for comprometido, revogue a chave em Configurações, API. Chaves revogadas não podem ser restauradas. Para encerrar uma conexão Sign in with Nomid, revogue-a na lista de conexões da página de agentes de IA no portal ou desconecte-a em um cliente que revoga seus tokens ao desconectar. De qualquer forma, a conexão e todos os seus tokens param de funcionar de imediato. Cada usuário pode revogar suas próprias conexões, e um usuário que pode gerenciar chaves de API pode revogar qualquer conexão da empresa.

Limites de taxa

Os limites são calculados por chave de API ou por conexão Sign in with Nomid, em janelas fixas de um minuto. Quando você excede o limite de solicitações MCP, o servidor responde com HTTP 429 Too Many Requests com um cabeçalho Retry-After que informa os segundos até a janela ser redefinida.

Uma chamada de ferramenta de comando, cada chamada de proposta ou aplicação de uma ferramenta de alteração de política e cada chamada de create_provisioning_qr_code contam para ambos os limites. Quando essa chamada excede o limite compartilhado de gravação, o servidor retorna um erro de ferramenta em vez de um HTTP 429. É uma resposta normal sinalizada como erro, e seu texto informa quantos segundos aguardar. Os endpoints de leitura REST não usam o limite de MCP.

Solução de problemas

Documentação relacionada

• Autenticação por chave de API
• Referência da API de comandos de dispositivo
• API de alterações de política
• API de códigos QR de provisionamento