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

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:

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):

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

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.

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.

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.

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

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.

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.

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>"}'

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

Claude
Claude Code
Cursor
Cliente genérico

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:

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.

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.

~/.cursor/mcp.json:

{ "mcpServers": { "didit": { "url": "https://mcp.didit.me/mcp" } } }

Cursor se registra por sí mismo y abre el navegador la primera vez que lo usas.

Configura cualquier cliente de Streamable HTTP compatible con OAuth 2.1 para que use https://mcp.didit.me/mcp. El cliente debe:

Hacer POST /mcp, recibir 401 y leer resource_metadata de WWW-Authenticate.
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.
Registrarse en el registration_endpoint si no tiene un ID de cliente.
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.
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

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.

Referencia de herramientas

Qué hace cada herramienta, su scope y el permiso de rol que requiere.

Avanzado

Roles, comportamiento entre aplicaciones y autoalojamiento.

Guías

Autenticación

Model Context Protocol (MCP)

SDKs web

SDKs nativos

SDK de servidor

Integraciones

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

Iniciar sesión con Didit

Scopes

Roles y permisos

Duración de los tokens

Desconectar una aplicación

Conectarse desde cada cliente

Errores de autenticación

Referencia de herramientas

Avanzado

​Iniciar sesión con Didit

​Scopes

​Roles y permisos

​Duración de los tokens

​Desconectar una aplicación

​Conectarse desde cada cliente

​Errores de autenticación

Referencia de herramientas

Avanzado

Iniciar sesión con Didit

Scopes

Roles y permisos

Duración de los tokens

Desconectar una aplicación

Conectarse desde cada cliente

Errores de autenticación