> 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/es/dev-reference/mcp-server.md).

# Servidor MCP

Servidor MCP de RealmJoin: punto de conexión, tokens de acceso MCP, configuración del cliente, las herramientas de solo lectura para el estado del dispositivo y los datos de software, límite de tasa y seguridad.

RealmJoin ejecuta un [Protocolo de contexto de modelo](https://modelcontextprotocol.io/) (MCP) como servidor en el marco de RealmJoin Customer-API. Los clientes MCP, por ejemplo asistentes de IA y agentes de IDE, se conectan a él con un token de acceso MCP y llaman a sus herramientas para leer el estado del dispositivo y los datos de software de tu Tenant.

Todas las herramientas son de solo lectura. El servidor MCP no puede cambiar dispositivos, paquetes, asignaciones ni configuraciones.

## Requisitos

* El servidor MCP está habilitado para tu Tenant. La función la habilita RealmJoin; contacta con el soporte de RealmJoin para que la habiliten.
* Crear y revocar tokens requiere un rol de administrador en el Portal de RealmJoin: el rol de RealmJoin **Administrador** o el rol de Entra ID **Global Administrator**  (política del Portal `CanAdministerOwnTenant`; no se puede conceder mediante [Roles personalizados](https://docs.realmjoin.com/es/administracion-y-configuracion/permission/custom-roles.md)). La **Acceso MCP** pestaña de configuración solo se muestra con este rol y mientras la función esté habilitada.
* Un cliente MCP que admite el transporte Streamable HTTP y puede enviar un encabezado personalizado `Authorization` El servidor MCP no ofrece inicio de sesión OAuth, así que los clientes que solo se conectan a servidores remotos mediante OAuth no pueden usarlo.

## Punto de conexión y autenticación

| Propiedad           | Valor                                    |
| ------------------- | ---------------------------------------- |
| URL                 | `https://customer-api.realmjoin.com/mcp` |
| Transporte          | Streamable HTTP                          |
| Autenticación       | `Authorization: Bearer <MCP token>`      |
| Nombre del servidor | `realmjoin`                              |

El punto de conexión solo acepta tokens de acceso MCP. El nombre de usuario y el secreto usados para [API de RealmJoin](https://docs.realmjoin.com/es/dev-reference/realmjoin-api/authentication.md) (HTTP Basic) no se aceptan aquí.

Cada solicitud se comprueba para verificar:

1. Un token válido: existe, no está expirado ni revocado, y su secreto coincide.
2. Un propietario autorizado: el usuario que creó el token todavía tiene una cuenta habilitada y un rol de administrador que alcanza el Tenant (ver [Comprobación del propietario del token](#token-owner-check)).
3. Un Tenant activo con la función del servidor MCP habilitada.

| Respuesta                    | Causa                                                                                                                                                            |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401 No autorizado`          | No hay token Bearer, token con formato incorrecto, token desconocido, expirado o revocado, o el propietario del token no supera la comprobación del propietario. |
| `403 Prohibido`              | La función del servidor MCP no está habilitada para el Tenant, o el Tenant está deshabilitado.                                                                   |
| `429 Demasiadas solicitudes` | Se agotó el límite de velocidad del Tenant (ver [Límite de velocidad](#rate-limit)).                                                                             |

## Tokens de acceso MCP

Los tokens de acceso MCP se administran en el Portal de RealmJoin en **bloque Settings** > **Acceso MCP**.

### Crear un token

{% stepper %}
{% step %}

### Abrir Acceso MCP

En el Portal de RealmJoin, abre **bloque Settings** > **Acceso MCP** y haz clic en **Agregar nuevo** (icono de más) junto al campo de búsqueda.
{% endstep %}

{% step %}

### Nombra el token y elige su duración

En **Nuevo token MCP**, introduce un **Nombre** que identifique al cliente o al propósito, por ejemplo `Claude Desktop` (obligatorio, hasta 100 caracteres). Selecciona **Expira después de**: 30, 90 (predeterminado), 180 o 365 días. Haz clic en **Crear**.

<figure><img src="https://3832142177-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>Nuevo token MCP</p></figcaption></figure>
{% endstep %}

{% step %}

### Copiar el token

El cuadro de diálogo **Token MCP creado** muestra el token una sola vez. Cópialo y guárdalo en un almacén de secretos antes de hacer clic en **Hecho**. RealmJoin almacena solo un hash del secreto del token, por lo que el token no puede mostrarse de nuevo. Si se pierde, crea un nuevo token y revoca el anterior.
{% endstep %}
{% endstepper %}

Un token tiene el formato `rjm_<tenant ID>.<token ID>.<secret>`. Está vinculado al Tenant seleccionado en el Portal cuando se crea el token y al usuario que lo crea. Un token creado por un administrador de partner en un Tenant de cliente da acceso solo a ese Tenant de cliente.

### Lista de tokens

Los **Acceso MCP** la pestaña enumera todos los tokens del Tenant, creados por cualquier administrador, ordenados del más reciente al más antiguo. El campo de búsqueda filtra por nombre y propietario.

<figure><img src="https://3832142177-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>Pestaña Acceso MCP</p></figcaption></figure>

| Columna    | Contenido                                                                                                                                                                              |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Nombre     | El nombre introducido al crear el token.                                                                                                                                               |
| Owner      | Nombre principal de usuario del usuario que creó el token. **Tu** marca tus propios tokens.                                                                                            |
| Estado     | **Válido**, **Expirado** o **Revocado**. Al pasar el cursor sobre **Revocado** muestra quién revocó el token.                                                                          |
| Caduca     | Hora de expiración. Los tokens creados antes de que la expiración fuera obligatoria muestran **después del siguiente uso**: obtienen una expiración de 90 días desde su siguiente uso. |
| Último uso | Hora de la última solicitud autenticada, actualizada como máximo una vez por minuto, o **nunca**.                                                                                      |
| Creado     | Hora de creación.                                                                                                                                                                      |

### Revocar un token

Haz clic en **Revocar** en la fila del token y confirma. Todo administrador puede revocar cualquier token válido del Tenant, incluidos los tokens de otros usuarios. La revocación surte efecto con la siguiente solicitud. Los tokens revocados y expirados permanecen en la lista con su estado; no pueden reactivarse.

### Comprobación del propietario del token

Un token actúa con el acceso del usuario que lo creó. En cada solicitud, RealmJoin comprueba al propietario en su Tenant de origen:

* La cuenta de usuario existe y está habilitada.
* El usuario posee actualmente un rol que concede `CanAdministerOwnTenant`: el rol de RealmJoin **Administrador** (ver [Roles predefinidos](https://docs.realmjoin.com/es/administracion-y-configuracion/permission/pre-defined-roles.md#admin-permissions)) o el rol activo de Entra ID **Global Administrator** .
* Para un Tenant distinto del Tenant de origen, el Tenant de origen está registrado como partner de ese Tenant.

El resultado se almacena en caché durante 5 minutos. Por lo tanto, una cuenta deshabilitada o un rol de administrador eliminado deja de funcionar para los tokens del usuario en 5 minutos, sin revocarlos. Si la comprobación no puede completarse, por ejemplo porque Microsoft Graph no está disponible, las solicitudes se deniegan durante 1 minuto.

{% hint style="warning" %}
La comprobación usa las membresías de grupo actuales del propietario y los roles de Active Directory activos. Si el acceso de administrador del propietario proviene de Privileged Identity Management (PIM), sus tokens solo funcionan mientras la membresía de grupo o el rol estén activados.
{% endhint %}

## Conectar un cliente

Configura el cliente con la URL del punto de conexión y un encabezado `Authorization` que lleve el token. El formato de configuración depende del cliente. Mantén el token fuera de los archivos de configuración que se confían al control de código fuente; usa en su lugar el mecanismo del cliente para variables de entorno o solicitudes de secretos.

{% tabs %}
{% tab title="Genérico (JSON de mcpServers)" %}
Los clientes que usan el formato JSON de `mcpServers` , con el token tomado de la variable de entorno `REALMJOIN_MCP_TOKEN`:

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

Si `${...}` las variables se expanden depende del 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"
```

El shell expande `$REALMJOIN_MCP_TOKEN` cuando se ejecuta el comando, y Claude Code almacena el encabezado resultante en su configuración.
{% endtab %}

{% tab title="VS Code" %}
`.vscode/mcp.json`; VS Code solicita el token en el primer inicio y lo almacena en su almacenamiento seguro:

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

{% endtab %}
{% endtabs %}

## Herramientas disponibles

Todas las herramientas devuelven JSON como texto y solo leen datos del Tenant al que está vinculado el token. Los datos del dispositivo provienen del estado del dispositivo que informa el agente de RealmJoin; los dispositivos sin el agente no se encuentran. Los datos de software provienen de [Software Reporting](https://docs.realmjoin.com/es/analizar-y-exportar/software-reporting.md).

| Herramienta           | Parámetros                                    | Devuelve                                                                                                   |
| --------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `get_tenant_overview` | ninguno                                       | Conteos activos y totales de dispositivos y usuarios, número de paquetes de software, umbral de actividad. |
| `search_devices`      | `query`                                       | Hasta 25 dispositivos que coinciden con un nombre de máquina o un prefijo de ID de dispositivo.            |
| `get_device_by_name`  | `name`                                        | Estado completo del dispositivo visto más recientemente con ese nombre.                                    |
| `get_device_state`    | `deviceId`, opcional `paths`, opcional `full` | Resumen, secciones seleccionadas o el estado completo de un dispositivo.                                   |
| `list_packages`       | opcional `search`                             | Hasta 50 paquetes de software con conteos de dispositivos y usuarios.                                      |
| `get_software_report` | `packageId`                                   | Versiones instaladas de un paquete con conteos de dispositivos, usuarios y uso.                            |

### get\_tenant\_overview

Devuelve:

* `Devices.Active` / `Devices.Total`: dispositivos vistos dentro del umbral de actividad, y todos los dispositivos.
* `Users.Active` / `Users.Total`: lo mismo para los usuarios.
* `SoftwarePackages`: número de paquetes de RealmJoin en el Tenant.
* `ActivityThreshold`: el tiempo de corte para "activo" (hora actual menos el período de actividad del Tenant, 90 días por defecto).

### search\_devices

`query` coincide con un dispositivo cuando el nombre de máquina lo contiene (sin distinción de mayúsculas y minúsculas) o el ID de cliente de RealmJoin, el ID de dispositivo de Entra o el ID de dispositivo de Intune empieza por él. Devuelve hasta 25 dispositivos, los vistos más recientemente primero, cada uno con `ClientID`, `UserID`, `MachineName`, `VersionTray` (versión del agente) y `ServerTimestamp` (último check-in). Cuando coinciden más dispositivos, la respuesta indica cuántos coincidieron en total.

### get\_device\_by\_name

`name` se compara sin distinción de mayúsculas y minúsculas con el nombre de host y el nombre de máquina; solo cuentan las coincidencias exactas. Si varios dispositivos comparten el nombre, se devuelve el visto más recientemente. La respuesta contiene el estado completo del dispositivo y se trunca a 20,000 caracteres; usa `get_device_state` con `paths` para secciones específicas.

### get\_device\_state

`deviceId` es un GUID: el ID de cliente de RealmJoin, el ID de dispositivo de Entra o el ID de dispositivo de Intune.

* Sin `paths` y `full`, la respuesta contiene estas secciones: `ClientID`, `MachineName`, `HostName`, `UserID`, `ServerTimestamp`, `VersionTray`, `OperatingSystem`, `Intune`, `Msoa`, `AzureAD`, `User`.
* `paths` reemplaza esta selección por las rutas de propiedad del estado del dispositivo enumeradas, por ejemplo `Intune`, `BranchCache`, `LocalAdminManagement` o `CustomStates.PrinterInventory`. Las rutas pueden contener letras, dígitos, guiones bajos, guiones, puntos e índices de matriz.
* `full: true` devuelve el estado completo del dispositivo.

Las respuestas de más de 20,000 caracteres se truncan, con una nota que indica la longitud total.

### list\_packages

Enumera paquetes de los datos de Software Reporting cuyo ID de paquete empieza por `generic-` (paquetes del Package Store), ordenados por número de dispositivos, como máximo 50. `search` filtra por una subcadena del ID de paquete, por ejemplo `chrome`. Cada entrada contiene `PackageId`, `DeviceCount` y `UserCount`.

### get\_software\_report

`packageId` debe coincidir exactamente con un ID de paquete, por ejemplo `generic-7zip`; usa `list_packages` para encontrarlo. Devuelve hasta 20 entradas, primero la versión más alta. Cada entrada contiene el ID del paquete, `Versión`, `Publisher`, el tipo de instalación, `DeviceCount`, `UserCount`, `LicenseCount`, los conteos de dispositivos, usuarios y licencias basados en ejecuciones, `TotalExecutions` y `LastExecution`.

## Límite de velocidad

Cada Tenant puede enviar 60 solicitudes por minuto al punto de conexión MCP, contadas en una ventana deslizante de seis segmentos de 10 segundos. El límite se aplica al Tenant, así que todos los tokens de un Tenant lo comparten. Las solicitudes por encima del límite se rechazan inmediatamente con `429 Demasiadas solicitudes`; no se ponen en cola.

Cada mensaje MCP es una solicitud HTTP separada, incluida la inicialización de la sesión y el listado de herramientas, por lo que un cliente usa más de una solicitud por llamada a herramienta. Las solicitudes rechazadas con `401` o `403` no cuentan.

## Consideraciones de seguridad

* **Alcance de un token:** un token da acceso de lectura al estado del dispositivo y a los datos de software de su Tenant, con el acceso del usuario que lo creó. Cualquiera que tenga el token puede usarlo hasta que caduque o se revoque.
* **Datos que salen de RealmJoin:** los resultados de las herramientas, incluidos los nombres de dispositivo, IDs de usuario y otro estado del dispositivo, se envían al cliente MCP y, para los asistentes de IA, al proveedor de modelo que usa el cliente. Comprueba que esto esté permitido para los datos de tu Tenant antes de conectar un cliente.
* **Almacenamiento:** almacena los tokens en un gestor de contraseñas o almacén de secretos, o en el almacenamiento seguro del cliente. No los confirmes en el control de código fuente, no los pegues en tickets o chats, ni compartas un token entre varias personas o clientes.
* **Duración y rotación:** elige la duración más corta que se ajuste al uso. Para rotarlo, crea un nuevo token, actualiza el cliente y luego revoca el token antiguo.
* **Revocación:** revoca los tokens que ya no se usan o que pudieron haberse expuesto. Todo administrador del Tenant puede revocar cualquier token en la **Acceso MCP** pestaña. **Último uso** para encontrar tokens no utilizados.
* **Cambios de propietario:** cuando el propietario abandona o pierde el rol de administrador, sus tokens dejan de funcionar en 5 minutos. Revócalos de todos modos para que la lista muestre su estado real.
* **Eliminación del Tenant:** al eliminar un Tenant se eliminan todos sus 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/es/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.
