For the complete documentation index, see llms.txt. This page is also available as Markdown.

Servidor MCP

Servidor RealmJoin MCP: endpoint, tokens de acesso MCP, configuração do cliente, as ferramentas apenas de leitura para o estado do dispositivo e dados de software, limite de taxa e segurança.

RealmJoin executa um Protocolo de Contexto do Modelo (MCP) como servidor no âmbito da RealmJoin Customer-API. Clientes MCP, por exemplo assistentes de IA e agentes de IDE, conectam-se a ele com um token de acesso MCP e chamam suas ferramentas para ler o estado do dispositivo e os dados de software do seu Tenant.

Todas as ferramentas são somente leitura. O servidor MCP não pode alterar dispositivos, pacotes, atribuições ou configurações.

Requisitos

  • O servidor MCP está ativado para o seu Tenant. O recurso é ativado pela RealmJoin; entre em contato com o Suporte da RealmJoin para que ele seja ativado.

  • Criar e revogar tokens exige uma role de administrador no RealmJoin Portal: o RealmJoin Admin role ou o Entra ID Administrador Global role (política do Portal CanAdministerOwnTenant; não pode ser concedida por meio de Funções personalizadas). O Acesso MCP guia de configurações só é exibida com essa role e enquanto o recurso estiver ativado.

  • Um cliente MCP que suporte o transporte Streamable HTTP e possa enviar um Authorization cabeçalho. O servidor MCP não oferece entrada via OAuth, portanto clientes que se conectam a servidores remotos apenas por OAuth não podem usá-lo.

Endpoint e autenticação

Propriedade
Valor

URL

https://customer-api.realmjoin.com/mcp

Transporte

Streamable HTTP

Autenticação

Authorization: Bearer <MCP token>

Nome do servidor

realmjoin

O endpoint aceita somente tokens de acesso MCP. O nome de usuário e o segredo usados para o RealmJoin API (HTTP Basic) não são aceitos aqui.

Cada solicitação é verificada quanto a:

  1. Um token válido: ele existe, não está expirado nem revogado, e seu segredo corresponde.

  2. Um proprietário autorizado: o usuário que criou o token ainda tem uma conta habilitada e uma role de administrador que concede acesso ao Tenant (veja Verificação do proprietário do token).

  3. Um Tenant ativo com o recurso do servidor MCP ativado.

Resposta
Causa

401 Não autorizado

Sem token bearer, token malformado, token desconhecido, expirado ou revogado, ou o proprietário do token falha na verificação do proprietário.

403 Proibido

O recurso do servidor MCP não está ativado para o Tenant, ou o Tenant está desativado.

429 Muitas solicitações

O limite de taxa do Tenant está esgotado (veja Limite de taxa).

Tokens de acesso MCP

Os tokens de acesso MCP são gerenciados no RealmJoin Portal em Configurações > Acesso MCP.

Criar um token

1

Abrir Acesso MCP

No RealmJoin Portal, abra Configurações > Acesso MCP e clique em Adicionar novo (ícone de mais) ao lado do campo de pesquisa.

2

Nomeie o token e escolha sua duração

Em Novo token MCP, insira um Nome que identifique o cliente ou a finalidade, por exemplo Claude Desktop (obrigatório, até 100 caracteres). Selecione Expira após: 30, 90 (padrão), 180 ou 365 dias. Clique em Criar.

New MCP token dialog with the fields Name and Expires after
Novo token MCP
3

Copie o token

A caixa de diálogo Token MCP criado mostra o token apenas uma vez. Copie-o e armazene-o em um cofre de segredos antes de clicar em Concluído. RealmJoin armazena apenas um hash do segredo do token, portanto o token não pode ser exibido novamente. Se ele for perdido, crie um novo token e revogue o antigo.

Um token tem o formato rjm_<tenant ID>.<token ID>.<secret>. Ele fica vinculado ao Tenant selecionado no Portal quando o token é criado e ao usuário que o cria. Um token criado por um administrador parceiro em um Tenant de cliente concede acesso somente a esse Tenant de cliente.

Lista de tokens

O Acesso MCP a guia lista todos os tokens do Tenant, criados por qualquer administrador, do mais recente para o mais antigo. O campo de pesquisa filtra por nome e proprietário.

MCP Access settings tab with the token list
Guia de Acesso MCP
Coluna
Conteúdo

Nome

O nome inserido na criação.

Proprietário

Nome principal do usuário que criou o token. Seus marca os seus próprios tokens.

Status

Válido, Expirado ou Revogado. Ao passar o mouse sobre Revogado mostra quem revogou o token.

Expira

Hora de expiração. Tokens criados antes de a expiração se tornar obrigatória mostram após o próximo uso: eles recebem uma expiração de 90 dias a partir do próximo uso.

Último uso

Hora da última solicitação autenticada, atualizada no máximo uma vez por minuto, ou nunca.

Criado

Hora de criação.

Revogar um token

Clique em Revogar na linha do token e confirme. Todo administrador pode revogar todo token válido do Tenant, incluindo tokens de outros usuários. A revogação entra em vigor com a próxima solicitação. Tokens revogados e expirados permanecem na lista com seu status; eles não podem ser reativados.

Verificação do proprietário do token

Um token age com o acesso do usuário que o criou. Em cada solicitação, RealmJoin verifica o proprietário em seu Tenant de origem:

  • A conta do usuário existe e está habilitada.

  • O usuário atualmente possui uma role que concede CanAdministerOwnTenant: o RealmJoin Admin role (veja Funções predefinidas) ou a role ativa do Entra ID Administrador Global role.

  • Para um Tenant diferente do Tenant de origem, o Tenant de origem é registrado como parceiro desse Tenant.

O resultado fica em cache por 5 minutos. Uma conta desativada ou uma role de administrador removida, portanto, faz com que os tokens do usuário parem de funcionar em até 5 minutos, sem revogá-los. Se a verificação não puder ser concluída, por exemplo porque o Microsoft Graph não estiver disponível, as solicitações são negadas por 1 minuto.

Conectar um cliente

Configure o cliente com a URL do endpoint e um Authorization cabeçalho que carrega o token. O formato da configuração depende do cliente. Mantenha o token fora de arquivos de configuração que sejam enviados ao controle de origem; em vez disso, use o mecanismo do cliente para variáveis de ambiente ou solicitações de segredos.

Clientes que usam o mcpServers formato JSON, com o token obtido da variável de ambiente REALMJOIN_MCP_TOKEN:

Se ${...} as variáveis são expandidas depende do cliente.

O shell expande $REALMJOIN_MCP_TOKEN quando o comando é executado, e o Claude Code armazena o cabeçalho resultante em sua configuração.

.vscode/mcp.json; o VS Code solicita o token na primeira inicialização e o armazena em seu armazenamento de segredos:

Ferramentas disponíveis

Todas as ferramentas retornam JSON como texto e leem apenas os dados do Tenant ao qual o token está vinculado. Os dados do dispositivo vêm do estado do dispositivo que o RealmJoin Agent relata; dispositivos sem o agente não são encontrados. Os dados de software vêm de Software Reporting.

Ferramenta
Parâmetros
Retorna

get_tenant_overview

nenhum

Contagens de dispositivos e usuários ativos e totais, número de pacotes de software, limiar de atividade.

search_devices

consulta

Até 25 dispositivos que correspondem a um nome de máquina ou a um prefixo de ID de dispositivo.

get_device_by_name

nome

Estado completo do dispositivo mais recentemente visto com esse nome.

get_device_state

deviceId, opcional caminhos, opcional completo

Resumo, seções selecionadas ou o estado completo de um dispositivo.

list_packages

opcional pesquisa

Até 50 pacotes de software com contagens de dispositivos e usuários.

get_software_report

packageId

Versões instaladas de um pacote com contagens de dispositivos, usuários e uso.

get_tenant_overview

Retorna:

  • Devices.Active / Devices.Total: dispositivos vistos dentro do limiar de atividade e todos os dispositivos.

  • Users.Active / Users.Total: o mesmo para usuários.

  • SoftwarePackages: número de pacotes RealmJoin no Tenant.

  • ActivityThreshold: o horário limite para "ativo" (hora atual menos o período de atividade do Tenant, 90 dias por padrão).

search_devices

consulta corresponde a um dispositivo quando o nome da máquina o contém (sem distinção entre maiúsculas e minúsculas) ou o ID de cliente do RealmJoin, o ID de dispositivo do Entra ID ou o ID de dispositivo do Intune começa com ele. Retorna até 25 dispositivos, do mais recente visto para o menos recente, cada um com ClientID, UserID, MachineName, VersionTray (versão do agente) e ServerTimestamp (último check-in). Quando mais dispositivos correspondem, a resposta informa quantos corresponderam no total.

get_device_by_name

nome é comparado sem distinção entre maiúsculas e minúsculas com o nome do host e o nome da máquina; apenas correspondências exatas contam. Se vários dispositivos compartilharem o nome, o mais recentemente visto é retornado. A resposta contém o estado completo do dispositivo e é truncada em 20.000 caracteres; use get_device_state com caminhos para seções específicas.

get_device_state

deviceId é um GUID: o ID de cliente do RealmJoin, o ID de dispositivo do Entra ID ou o ID de dispositivo do Intune.

  • Sem caminhos e completo, a resposta contém estas seções: ClientID, MachineName, HostName, UserID, ServerTimestamp, VersionTray, OperatingSystem, Intune, Msoa, AzureAD, User.

  • caminhos substitui essa seleção pelos caminhos de propriedades listados do estado do dispositivo, por exemplo Intune, BranchCache, LocalAdminManagement ou CustomStates.PrinterInventory. Os caminhos podem conter letras, dígitos, sublinhados, hífens, pontos e índices de array.

  • full: true retorna o estado completo do dispositivo.

Respostas com mais de 20.000 caracteres são truncadas, com uma nota que informa o comprimento total.

list_packages

Lista pacotes dos dados do Software Reporting cujo ID de pacote começa com generic- (pacotes do Package Store), ordenados por contagem de dispositivos, no máximo 50. pesquisa filtra por uma substring do ID do pacote, por exemplo chrome. Cada entrada contém PackageId, DeviceCount e UserCount.

get_software_report

packageId deve corresponder exatamente a um ID de pacote, por exemplo generic-7zip; use list_packages para encontrá-lo. Retorna até 20 entradas, com a versão mais alta primeiro. Cada entrada contém o ID do pacote, Versão, Publisher, o tipo de instalação, DeviceCount, UserCount, LicenseCount, as contagens de dispositivos, usuários e licenças com base nas execuções, TotalExecutions e LastExecution.

Limite de taxa

Cada Tenant pode enviar 60 solicitações por minuto para o endpoint MCP, contadas em uma janela deslizante de seis segmentos de 10 segundos. O limite se aplica ao Tenant, portanto todos os tokens de um Tenant o compartilham. As solicitações além do limite são rejeitadas imediatamente com 429 Muitas solicitações; elas não entram em fila.

Cada mensagem MCP é uma solicitação HTTP separada, incluindo a inicialização da sessão e a listagem de ferramentas, portanto um cliente usa mais de uma solicitação por chamada de ferramenta. As solicitações rejeitadas com 401 ou 403 não contam.

Considerações de segurança

  • Escopo de um token: um token concede acesso de leitura ao estado do dispositivo e aos dados de software do seu Tenant, com o acesso do usuário que o criou. Qualquer pessoa que possua o token pode usá-lo até que ele expire ou seja revogado.

  • Dados que saem do RealmJoin: os resultados das ferramentas, incluindo nomes de dispositivos, IDs de usuário e outro estado do dispositivo, são passados ao cliente MCP e, para assistentes de IA, ao provedor de modelo usado pelo cliente. Verifique se isso é permitido para os dados do seu Tenant antes de conectar um cliente.

  • Armazenamento: armazene os tokens em um gerenciador de senhas ou cofre de segredos, ou no armazenamento de segredos do cliente. Não os confirme no controle de origem, não os cole em tickets ou chats, nem compartilhe um token entre várias pessoas ou clientes.

  • Duração e rotação: escolha a menor duração que se ajuste ao uso. Para fazer a rotação, crie um novo token, atualize o cliente e depois revogue o token antigo.

  • Revogação: revogue tokens que não são mais usados ou que possam ter sido expostos. Todo administrador do Tenant pode revogar qualquer token na Acesso MCP guia. Verifique Último uso para encontrar tokens não utilizados.

  • Mudanças de proprietário: quando o proprietário sai ou perde a role de administrador, seus tokens param de funcionar em até 5 minutos. Revogue-os de qualquer forma para que a lista mostre seu estado real.

  • Exclusão do Tenant: excluir um Tenant exclui todos os seus tokens MCP.

Última atualização

Isto foi útil?