Autenticació MCP de Didit: inici de sessió amb OAuth

El servidor MCP de Didit s’autentica amb Iniciar sessió amb Didit (OAuth 2.1). Actua com un usuari de Didit amb els permisos del rol que tens a la consola, i no hi ha cap mode amb clau d’API.

Iniciar sessió amb Didit

El servidor allotjat (https://mcp.didit.me/mcp) és un servidor de recursos OAuth 2.1. La Didit Business Console (business.didit.me) és el servidor d’autorització que aloja la pantalla de consentiment i emet els tokens. El teu client MCP segueix el flux estàndard automàticament:

Descobriment

El client envia una petició a /mcp sense token i rep un 401 amb una capçalera WWW-Authenticate: Bearer el resource_metadata de la qual apunta a les metadades del recurs protegit (RFC 9728):

https://mcp.didit.me/.well-known/oauth-protected-resource/mcp

Aquest document indica el recurs (https://mcp.didit.me/mcp), el servidor d’autorització (https://business.didit.me) i els àmbits admesos. El mateix document també es publica a l’arrel de l’origen, https://mcp.didit.me/.well-known/oauth-protected-resource, per als clients que el consulten primer en aquest punt.

Registre (registre dinàmic de clients)

El client llegeix les metadades del servidor d’autorització a https://business.didit.me/.well-known/oauth-authorization-server i, si encara no té un ID de client, es registra a l’registration_endpoint (RFC 7591). No cal que facis cap aprovisionament previ: els clients locals amb un callback de loopback o natiu (Claude Code, Cursor, MCP Inspector) i els clients allotjats al núvol amb un callback revisat (Claude) es registren d’aquesta manera. Una URL de callback remota que Didit no ha revisat es rebutja amb invalid_redirect_uri; aquest client necessita que un operador el registri primer.

Autoritza (PKCE)

El client obre https://business.didit.me/authorize amb un desafiament PKCE S256. Tu inicies sessió (o et registres) i veus exactament quins permisos es demanen. Els clients són públics: l’endpoint del token no accepta cap secret de client (token_endpoint_auth_methods_supported és none), de manera que el PKCE és el que lliga el codi al client.

Consentiment

Tu aproves. La consola crea una sessió per a aquesta aplicació, lligada als àmbits que has aprovat, i retorna un codi d’autorització, que el client intercanvia a l’token_endpoint per obtenir un token d’accés i un token de renovació.

Crida les eines

El client envia el token d’accés amb cada petició. El MCP el valida mitjançant la introspecció de tokens RFC 7662 contra el servei d’autenticació de Didit (els tokens són opacs, no JWT), llegeix els permisos de la teva organització de la resposta d’introspecció i actua com tu durant aquella petició.

Àmbits

Les metadades del recurs anuncien tres àmbits. La pantalla de consentiment mostra en llenguatge senzill els que un client demana:

Àmbit	Concedeix
`didit:management`	Gestiona el teu espai de treball: `organization`, `members`, `subscription`, `users`, `applications`, `workflows`, `customization`, `questionnaires`, `lists`, `webhooks`, `integrations`, `api-keys`, `audit-logs`, `roles`, `saml` i `analytics`.
`didit:verification`	Executa i revisa verificacions: `sessions`, `businesses`, `cases`, `networks`, `transactions`, `blocklist` i `analytics`.
`didit:staff`	Reservat per als comptes del personal de Didit. No desbloqueja res per a un compte habitual, i la versió de codi obert no defineix cap eina exclusiva del personal.

Ambdós àmbits inclouen analytics. Gestionar lists requereix didit:management; accedir a blocklist requereix didit:verification. La referència d’eines indica l’àmbit al qual pertany cada eina. Els àmbits que aproves es transporten al token i s’apliquen al servidor, de manera que una aplicació connectada només amb didit:verification es rebutja a la superfície de gestió, fins i tot si el teu rol propi ho permetria. El servidor d’autorització també coneix els àmbits d’OpenID (openid profile email); una connexió que només en demani aquests pot saber qui ets i res més. Els permisos efectius d’una aplicació són la intersecció dels àmbits aprovats i del teu rol a la consola, mai el més ampli dels dos. Per crear una sessió de verificació amb didit_session_create necessites l’àmbit didit:verification i un rol amb create:sessions o write:sessions. El rol Desenvolupador inclou create:sessions. Aprovar només didit:management no permet crear sessions, encara que el teu rol tingui el permís necessari.

Rols i permisos

El token emès pel servidor allotjat et representa, de manera que l’agent pot treballar a totes les organitzacions de les quals ets membre en una única connexió: les eines entre aplicacions (didit_session_search, didit_analytics, didit_context_get i la resta d’eines *_search) hi agreguen dades automàticament. El backend de Didit aplica sempre el teu rol, per organització. Cada eina correspon a una cadena de permís del backend (per exemple write:sessions per a didit_session_update_status, delete:sessions per a didit_session_delete); la referència d’eines n’indica el permís per eina. El servidor també comprova aquest permís abans d’enviar la petició, fent servir els permisos que la resposta d’introspecció porta per a la teva organització:

En mode enforce, una eina que el teu rol no pot executar s’omet de tools/list, i si es crida igualment es retorna un error missing_scope que indica el permís ("Your role in this organization does not include the permission 'delete:sessions' that didit_session_delete requires.").
En mode shadow (el valor per defecte del servidor) totes les eines es mostren i la crida passa al backend, que respon amb 403 si el rol no té el permís; el veredicte només es registra al registre d’auditoria del servidor.

En qualsevol dels dos casos, el MCP mai no concedeix més del que el teu rol de la consola ja permet. Un READER pot llistar i llegir; un OWNER o un ADMIN pot escriure i eliminar.

Durada del token

Una aplicació aprovada obté la seva pròpia sessió, separada de la sessió del navegador des de la qual l’has aprovat. Els tokens d’accés són de vida curta; el client els renova en silenci amb el token de renovació (grant_types_supported inclou refresh_token), i una renovació manté els àmbits de l’aplicació i continua lligada a aquesta aplicació. Si una renovació falla (per exemple, després que desconnectis l’aplicació), el client torna a executar Iniciar sessió amb Didit a la següent crida. Tancar la sessió de la consola no tanca la sessió de les aplicacions connectades, i desconnectar una aplicació mai no et tanca la sessió enlloc.

Desconnectar una aplicació

Des de la consola

Settings → Authentication → Connected apps mostra totes les aplicacions que has aprovat, amb el seu nom registrat i els permisos que se li han concedit. Desconnectar acaba l’accés d’aquella aplicació immediatament: tant el seu token d’accés com el seu token de renovació deixen de funcionar, i no afecta res més.

Des de l'aplicació (RFC 7009)

Un client pot retirar el seu propi accés enviant el token al revocation_endpoint del servidor d’autorització, que s’anuncia a les metadades de https://business.didit.me/.well-known/oauth-authorization-server. Tal com exigeix la RFC 7009, una crida satisfactòria respon 200 tant si el token encara era vàlid com si no, de manera que la resposta mai no et diu si un token era vàlid. Un 503 vol dir que la revocació no s’ha pogut aplicar: considera que el token encara és vàlid i reintenta.

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

Per què no hi ha clau d’API? Totes les eines MCP criden els endpoints de la consola amb abast d’usuari (/organization/{org}/application/{app}/…), que autoritzen un token Bearer amb privilegis per rol i rebutgen x-api-key. Una clau d’API d’aplicació serveix per cridar directament l’API REST des del teu propi backend (per exemple, per crear sessions), però no per a aquest MCP. didit_org_list_api_keys mostra les metadades de la clau amb els valors ocultats; l’eina que revela una clau en brut està amagada al connector allotjat.

Connectar des de cada client

Tots els clients segueixen el mateix flux; només canvia la manera de indicar-los la URL.

Claude
Claude Code
Cursor
Client genèric

Fes servir l’enllaç directe que la Business Console mostra a la seva pàgina d’integració. Obre claude.ai amb el diàleg Add custom connector ja omplert:

https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Didit&connectorUrl=https://mcp.didit.me/mcp

Confirma i després completa Iniciar sessió amb Didit. Claude Desktop fa servir la mateixa URL a Settings → Connectors → Add custom connector. Més detalls a Connecta Claude.

claude mcp add --transport http didit https://mcp.didit.me/mcp

Després executa /mcp dins de Claude Code per iniciar la sessió al navegador.

~/.cursor/mcp.json:

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

Cursor es registra automàticament i obre el navegador en el primer ús.

Apunta qualsevol client Streamable HTTP amb suport d’OAuth 2.1 a https://mcp.didit.me/mcp. Hauria de:

Fer POST /mcp, rebre un 401 i llegir resource_metadata de WWW-Authenticate.
Obtenir https://mcp.didit.me/.well-known/oauth-protected-resource/mcp i, després, les metadades del servidor d’autorització a https://business.didit.me/.well-known/oauth-authorization-server.
Registrar-se al registration_endpoint si no té un identificador de client.
Executar el flux de codi d’autorització amb PKCE (S256) al authorization_endpoint i intercanviar el codi al token_endpoint.
Enviar Authorization: Bearer <access_token> a cada POST /mcp.

Els clients sense suport d’OAuth poden funcionar darrere de npx -y mcp-remote@latest https://mcp.didit.me/mcp, que fa els passos 1–5 per ells.

Errors d’autenticació

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 des de /mcp vol dir que falta el token, ha caducat o s’ha revocat: el client hauria de renovar-lo o tornar a executar Iniciar sessió amb Didit. Un 403 o un error missing_scope en una eina concreta normalment vol dir que el teu rol no té aquell permís (per exemple, un READER que intenta una escriptura) o que la connexió s’ha aprovat sense l’abast que necessita aquella eina. No vol dir que tota la connexió estigui trencada. Tornar a connectar i aprovar tots dos abasts soluciona el segon cas; el primer requereix canviar el rol. Si fallen totes les eines, revisa Settings → Authentication → Connected apps a la consola: una aplicació que s’ha desconnectat des d’allà s’ha de tornar a aprovar.

Referència d'eines

Què fa cada eina, el seu abast i el permís del seu rol.

Avançat

Rols, comportament entre aplicacions i autoallotjament.

Guies

Autenticació

Model Context Protocol (MCP)

SDK web

SDK natius

SDK de servidor

Integracions

Autenticació MCP de Didit: inici de sessió amb OAuth

Iniciar sessió amb Didit

Àmbits

Rols i permisos

Durada del token

Desconnectar una aplicació

Connectar des de cada client

Errors d’autenticació

Referència d'eines

Avançat

​Iniciar sessió amb Didit

​Àmbits

​Rols i permisos

​Durada del token

​Desconnectar una aplicació

​Connectar des de cada client

​Errors d’autenticació

Referència d'eines

Avançat

Iniciar sessió amb Didit

Àmbits

Rols i permisos

Durada del token

Desconnectar una aplicació

Connectar des de cada client

Errors d’autenticació