> For the complete documentation index, see [llms.txt](https://docs.realmjoin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realmjoin.com/pt/dev-reference/mcp-server.md).

# 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](https://modelcontextprotocol.io/) (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](https://docs.realmjoin.com/pt/administracao-e-definicoes/permission/custom-roles.md)). 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](https://docs.realmjoin.com/pt/dev-reference/realmjoin-api/authentication.md) (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](#token-owner-check)).
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](#rate-limit)).                                                                 |

## Tokens de acesso MCP

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

### Criar um token

{% stepper %}
{% step %}

### 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.
{% endstep %}

{% step %}

### 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**.

<figure><img src="https://686519968-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2Fgit-blob-5eaace9fadaabec3068651837b60d659c666e233%2Fmcp-new-token.png?alt=media" alt="New MCP token dialog with the fields Name and Expires after"><figcaption><p>Novo token MCP</p></figcaption></figure>
{% endstep %}

{% step %}

### 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.
{% endstep %}
{% endstepper %}

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.

<figure><img src="https://686519968-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2Fgit-blob-e4e64be11dc0e2b77352f58966b158091cbbc968%2Fsettings-mcp-access.png?alt=media" alt="MCP Access settings tab with the token list"><figcaption><p>Guia de Acesso MCP</p></figcaption></figure>

| 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](https://docs.realmjoin.com/pt/administracao-e-definicoes/permission/pre-defined-roles.md#admin-permissions)) 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.

{% hint style="warning" %}
A verificação usa as associações atuais do proprietário a grupos e roles do Active Directory. Se o acesso de administrador do proprietário vier do Privileged Identity Management (PIM), seus tokens só funcionam enquanto a associação ao grupo ou a role estiver ativada.
{% endhint %}

## 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.

{% tabs %}
{% tab title="Genérico (JSON mcpServers)" %}
Clientes que usam o `mcpServers` formato JSON, com o token obtido da variável de ambiente `REALMJOIN_MCP_TOKEN`:

```json
{
  "mcpServers": {
    "realmjoin": {
      "type": "http",
      "url": "https://customer-api.realmjoin.com/mcp",
      "headers": {
        "Authorization": "Bearer ${REALMJOIN_MCP_TOKEN}"
      }
    }
  }
}
```

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

{% tab title="Claude Code" %}

```bash
claude mcp add --transport http realmjoin https://customer-api.realmjoin.com/mcp \\
  --header "Authorization: Bearer $REALMJOIN_MCP_TOKEN"
```

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

{% tab title="VS Code" %}
`.vscode/mcp.json`; o VS Code solicita o token na primeira inicialização e o armazena em seu armazenamento de segredos:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "realmjoin-mcp-token",
      "description": "Token MCP do RealmJoin",
      "password": true
    }
  ],
  "servers": {
    "realmjoin": {
      "type": "http",
      "url": "https://customer-api.realmjoin.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:realmjoin-mcp-token}"
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

## 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](https://docs.realmjoin.com/pt/analisar-e-exportar/software-reporting.md).

| 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.realmjoin.com/pt/dev-reference/mcp-server.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
