> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticación MCP de Didit: acceso con Didit (OAuth)

> El MCP de Didit usa OAuth 2.1 con PKCE, registro dinámico de clientes, metadatos de recursos, scopes y roles. Cómo conectar cada cliente.

El MCP de Didit se autentica con **Iniciar sesión con Didit** (OAuth 2.1). Actúa como un **usuario** de Didit con los permisos de tu rol en la consola: **no existe un modo de clave de API**.

***

## Iniciar sesión con Didit

El servidor alojado (`https://mcp.didit.me/mcp`) es un **servidor de recursos** OAuth 2.1. La **Didit Business Console** (`business.didit.me`) es el **servidor de autorización**: aloja la pantalla de consentimiento y emite los tokens. Tu cliente MCP ejecuta automáticamente el flujo estándar:

**1. Descubrimiento**

El cliente envía un POST a `/mcp` sin token y recibe un `401` con un encabezado `WWW-Authenticate: Bearer` cuyo `resource_metadata` apunta a los metadatos del recurso protegido (RFC 9728):

```text theme={null}
https://mcp.didit.me/.well-known/oauth-protected-resource/mcp
```

Ese documento indica el recurso (`https://mcp.didit.me/mcp`), el servidor de autorización (`https://business.didit.me`) y los scopes admitidos. El mismo documento también se sirve en la raíz del origen, `https://mcp.didit.me/.well-known/oauth-protected-resource`, para los clientes que lo buscan primero ahí.

**2. Registro (registro dinámico de clientes)**

El cliente lee los metadatos del servidor de autorización en `https://business.didit.me/.well-known/oauth-authorization-server` y, si aún no tiene un client id, se registra en el `registration_endpoint` (RFC 7591). No tienes que preparar nada por tu parte: los clientes locales con un callback de loopback o nativo (Claude Code, Cursor, MCP Inspector) y los clientes alojados en la nube con un callback revisado (Claude) se registran de esta forma. Una URL de callback remota que Didit no ha revisado se rechaza con `invalid_redirect_uri`; ese cliente necesita que un operador lo registre primero.

**3. Autorización (PKCE)**

El cliente abre `https://business.didit.me/authorize` con un desafío PKCE S256. Inicias sesión (o te registras) y ves exactamente qué permisos se solicitan. Los clientes son públicos: el endpoint de tokens no acepta ningún secreto de cliente (`token_endpoint_auth_methods_supported` es `none`), así que PKCE es lo que vincula el código al cliente.

**4. Consentimiento**

Das tu aprobación. La consola crea una sesión para esa aplicación, vinculada a los scopes que aprobaste, y devuelve un código de autorización, que el cliente intercambia en el `token_endpoint` por un token de acceso y un token de actualización.

**5. Llamada a herramientas**

El cliente envía el token de acceso en cada solicitud. El MCP lo valida mediante la introspección de tokens RFC 7662 contra el servicio de autenticación de Didit (los tokens son opacos, no JWT), lee los permisos de tu organización de la respuesta de introspección y actúa **en tu nombre** durante esa solicitud.

### Scopes

Los metadatos del recurso anuncian tres scopes. La pantalla de consentimiento muestra en lenguaje sencillo los que solicita cada cliente:

| Scope | Concede |
| - | - |
| `didit:management` | Gestionar tu espacio de trabajo: `organization`, `members`, `subscription`, `users`, `applications`, `workflows`, `customization`, `questionnaires`, `lists`, `webhooks`, `integrations`, `api-keys`, `audit-logs`, `roles`, `saml` y `analytics`. |
| `didit:verification` | Ejecutar y revisar verificaciones: `sessions`, `businesses`, `cases`, `networks`, `transactions`, `blocklist` y `analytics`. |
| `didit:staff` | Reservado para las cuentas del personal de Didit. No desbloquea nada en una cuenta normal, y la versión de código abierto no define herramientas exclusivas para el personal. |

Ambos scopes incluyen `analytics`. Gestionar `lists` requiere `didit:management`; acceder a `blocklist` requiere `didit:verification`.

La [referencia de herramientas](https://docs.didit.me/es/integration/mcp/tools.md) indica el scope al que pertenece cada herramienta. Los scopes que apruebas viajan en el token y se aplican en el servidor, de modo que una aplicación conectada solo con `didit:verification` se le deniega el acceso a las funciones de gestión aunque tu propio rol lo permita. El servidor de autorización también reconoce los scopes de OpenID (`openid profile email`); una conexión que solicita solo esos puede saber quién eres y nada más.

Los permisos efectivos de una aplicación son la **intersección** de los scopes aprobados y tu rol en la consola, nunca el más amplio de los dos.

Para crear una sesión de verificación con `didit_session_create`, necesitas el scope `didit:verification` **y** un rol con `create:sessions` o `write:sessions`. El rol **Developer** incluye `create:sessions`. Aprobar solo `didit:management` no permite crear sesiones, aunque tu rol tenga el permiso necesario.

### Roles y permisos

El token del servidor alojado te representa **a ti**, así que el agente puede trabajar en **todas las organizaciones a las que perteneces** con una sola conexión: las herramientas que abarcan varias aplicaciones (`didit_session_search`, `didit_analytics`, `didit_context_get` y las demás herramientas `*_search`) agregan los datos de todas ellas automáticamente.

El backend de Didit **siempre aplica tu rol**, por organización. Cada herramienta corresponde a una cadena de permiso del backend (por ejemplo, `write:sessions` para `didit_session_update_status` y `delete:sessions` para `didit_session_delete`); la [referencia de herramientas](https://docs.didit.me/es/integration/mcp/tools.md) la muestra para cada herramienta. El servidor también comprueba ese permiso antes de enviar la solicitud, usando los permisos que la respuesta de introspección incluye para tu organización:

* En el modo `enforce`, una herramienta que tu rol no puede ejecutar se omite de `tools/list`, y si la invocas de todos modos devuelve un error `missing_scope` que indica el permiso (`"Your role in this organization does not include the permission 'delete:sessions' that didit_session_delete requires."`).
* En el modo `shadow` (el predeterminado del servidor), se listan todas las herramientas y la llamada llega al backend, que responde `403` cuando el rol no tiene el permiso; el veredicto solo se registra en el registro de auditoría del servidor.

En cualquier caso, el MCP nunca concede más de lo que tu rol en la consola ya permite. Un `READER` puede listar y leer; un `OWNER` o un `ADMIN` puede escribir y eliminar.

### Duración de los tokens

Una aplicación aprobada obtiene su propia sesión, independiente de la sesión del navegador desde la que la aprobaste. Los tokens de acceso tienen una duración corta; el cliente los renueva de forma transparente con el token de actualización (`grant_types_supported` incluye `refresh_token`), y una renovación conserva los scopes de la aplicación y sigue vinculada a esa aplicación. Si una renovación falla (por ejemplo, después de que desconectes la aplicación), el cliente vuelve a ejecutar **Iniciar sesión con Didit** en la siguiente llamada.

Cerrar sesión en la consola no cierra la sesión de las aplicaciones conectadas, y desconectar una aplicación nunca cierra tu sesión en ningún sitio.

### Desconectar una aplicación

**1. Desde la consola**

**Settings → Authentication → Connected apps** muestra todas las aplicaciones que has aprobado, con su nombre registrado y los permisos que se les concedieron. **Disconnect** pone fin de inmediato al acceso de esa aplicación: tanto su token de acceso como su token de actualización dejan de funcionar, y nada más se ve afectado.

**2. Desde la aplicación (RFC 7009)**

Un cliente puede renunciar a su propio acceso enviando el token mediante POST al `revocation_endpoint` del servidor de autorización, publicado en los metadatos de `https://business.didit.me/.well-known/oauth-authorization-server`. Tal como exige RFC 7009, una llamada exitosa responde `200` tanto si el token seguía activo como si no, así que la respuesta nunca te indica si un token era válido. Un `503` significa que no se pudo aplicar la revocación: considera que el token sigue siendo válido y vuelve a intentarlo.

```bash theme={null}
curl -X POST https://business.didit.me/api/auth/oauth-revoke \
  -H "Content-Type: application/json" \
  -d '{"token": "<refresh-or-access-token>", "token_type_hint": "refresh_token", "client_id": "<your-client-id>"}'
```

> [!NOTE]
>
> **¿Por qué no hay clave de API?** Todas las herramientas MCP llaman a los endpoints de la consola asociados al usuario (`/organization/{org}/application/{app}/…`), que autorizan un token Bearer con privilegios por rol y **rechazan `x-api-key`**. La clave de API de una aplicación sirve para llamar a la [API REST](https://docs.didit.me/openapi-25.json) directamente desde tu propio backend (por ejemplo, para crear sesiones), no para este MCP. `didit_org_list_api_keys` muestra los metadatos de las claves con los valores ocultos; la herramienta que revela una clave en claro está oculta en el conector alojado.

***

## Conectarse desde cada cliente

Todos los clientes siguen el mismo flujo; solo cambia la forma de indicarles la URL.

> [tab] Claude
>
> Usa el enlace profundo que muestra la Business Console en su página de integración. Abre claude.ai con el cuadro de diálogo **Add custom connector** ya rellenado:
>
> ```text theme={null}
> https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Didit&connectorUrl=https://mcp.didit.me/mcp
> ```
>
> Confirma y, después, completa **Log in with Didit**. Claude Desktop usa la misma URL en **Settings → Connectors → Add custom connector**. Más detalles en [Conectar Claude](https://docs.didit.me/es/integration/mcp/claude.md).

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http didit https://mcp.didit.me/mcp
> ```
>
> Después ejecuta `/mcp` dentro de Claude Code para iniciar sesión en el navegador.

> [tab] Cursor
>
> `~/.cursor/mcp.json`:
>
> ```json theme={null}
> { "mcpServers": { "didit": { "url": "https://mcp.didit.me/mcp" } } }
> ```
>
> Cursor se registra por sí mismo y abre el navegador la primera vez que lo usas.

> [tab] Cliente genérico
>
> Configura cualquier cliente de Streamable HTTP compatible con OAuth 2.1 para que use `https://mcp.didit.me/mcp`. El cliente debe:
>
> 1. Hacer `POST /mcp`, recibir `401` y leer `resource_metadata` de `WWW-Authenticate`.
> 2. Obtener `https://mcp.didit.me/.well-known/oauth-protected-resource/mcp` y, después, los metadatos del servidor de autorización en `https://business.didit.me/.well-known/oauth-authorization-server`.
> 3. Registrarse en el `registration_endpoint` si no tiene un ID de cliente.
> 4. Ejecutar el flujo de código de autorización con PKCE (S256) en el `authorization_endpoint` e intercambiar el código en el `token_endpoint`.
> 5. Enviar `Authorization: Bearer <access_token>` en cada `POST /mcp`.
>
> Los clientes sin compatibilidad con OAuth pueden usar `npx -y mcp-remote@latest https://mcp.didit.me/mcp`, que realiza los pasos 1 a 5 por ellos.

***

## Errores de autenticación

```text theme={null}
HTTP 401
WWW-Authenticate: Bearer error="invalid_token", error_description="Missing Authorization header", resource_metadata="https://mcp.didit.me/.well-known/oauth-protected-resource/mcp"
```

Un `401` de `/mcp` significa que el token falta, ha expirado o ha sido revocado: el cliente debe renovarlo o volver a ejecutar **Iniciar sesión con Didit**.

Un `403` o un error `missing_scope` en una herramienta *concreta* suele significar que tu **rol** no tiene ese permiso (por ejemplo, un `READER` que intenta realizar una operación de escritura) o que la conexión se aprobó **sin el scope** que necesita esa herramienta, no que toda la conexión esté rota. Volver a conectarte y aprobar ambos scopes resuelve el segundo caso; el primero requiere un cambio de rol.

Si fallan todas las herramientas, revisa **Settings → Authentication → Connected apps** en la consola: una aplicación que se desconectó allí debe aprobarse de nuevo.

***

> [card] [Referencia de herramientas](https://docs.didit.me/es/integration/mcp/tools.md)
>
> Qué hace cada herramienta, su scope y el permiso de rol que requiere.

> [card] [Avanzado](https://docs.didit.me/es/integration/mcp/advanced.md)
>
> Roles, comportamiento entre aplicaciones y autoalojamiento.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.