Autenticazione MCP di Didit: accedi con Didit (OAuth)

Il server MCP di Didit si autentica con Accedi con Didit (OAuth 2.1). Agisce come utente Didit con le autorizzazioni del ruolo che hai nella console — non esiste una modalità con chiave API.

Accedi con Didit

Il server ospitato (https://mcp.didit.me/mcp) è un server delle risorse OAuth 2.1. La Didit Business Console (business.didit.me) è il server di autorizzazione che ospita la schermata di consenso ed emette i token. Il tuo client MCP esegue automaticamente il flusso standard:

Scoperta

Il client invia una richiesta a /mcp senza token e riceve 401 con un’intestazione WWW-Authenticate: Bearer il cui resource_metadata punta ai metadati della risorsa protetta (RFC 9728):

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

Quel documento indica la risorsa (https://mcp.didit.me/mcp), il server di autorizzazione (https://business.didit.me) e gli scope supportati. Lo stesso documento è disponibile anche alla radice dell’origine, https://mcp.didit.me/.well-known/oauth-protected-resource, per i client che provano prima quel percorso.

Registrazione (registrazione dinamica del client)

Il client legge i metadati del server di autorizzazione all’indirizzo https://business.didit.me/.well-known/oauth-authorization-server e, se non ha ancora un client id, si registra presso il registration_endpoint (RFC 7591). Non devi predisporre nulla: i client locali con callback loopback o nativo (Claude Code, Cursor, MCP Inspector) e i client cloud con un callback verificato (Claude) si registrano in questo modo. Un URL di callback remoto che Didit non ha verificato viene rifiutato con invalid_redirect_uri; per quel client è necessario che un operatore lo registri prima.

Autorizzazione (PKCE)

Il client apre https://business.didit.me/authorize con una challenge PKCE S256. Accedi (o ti registri) e vedi esattamente quali autorizzazioni vengono richieste. I client sono pubblici: l’endpoint del token non accetta alcun segreto client (token_endpoint_auth_methods_supported è none), quindi è PKCE a legare il codice al client.

Consenso

Approvi. La console crea una sessione per quell’app, vincolata agli scope che hai approvato, e restituisce un codice di autorizzazione, che il client scambia al token_endpoint per un token di accesso e un token di aggiornamento.

Chiamata degli strumenti

Il client invia l’access token con ogni richiesta. L’MCP valida il token tramite introspezione del token RFC 7662 presso il servizio di autenticazione di Didit (i token sono opachi, non JWT), legge le autorizzazioni della tua organizzazione dalla risposta dell’introspezione del token e agisce come te per la durata di quella richiesta.

Scope

I metadati della risorsa espongono tre scope. La schermata di consenso mostra in linguaggio semplice quelli richiesti da un client:

Scope	Concede
`didit:management`	Gestisci la tua area di lavoro: `organization`, `members`, `subscription`, `users`, `applications`, `workflows`, `customization`, `questionnaires`, `lists`, `webhooks`, `integrations`, `api-keys`, `audit-logs`, `roles`, `saml` e `analytics`.
`didit:verification`	Esegui e rivedi le verifiche: `sessions`, `businesses`, `cases`, `networks`, `transactions`, `blocklist` e `analytics`.
`didit:staff`	Riservato agli account dello staff di Didit. Non sblocca nulla per un account normale, e la build open source non definisce strumenti riservati allo staff.

Entrambi gli scope includono analytics. Gestire lists richiede didit:management; accedere a blocklist richiede didit:verification. Il riferimento degli strumenti elenca lo scope di ciascuno strumento. Gli scope che approvi vengono riportati nel token e applicati lato server, quindi un’app collegata con il solo didit:verification viene rifiutata sulla superficie di gestione anche quando il tuo ruolo lo consentirebbe. Il server di autorizzazione conosce anche gli scope OpenID (openid profile email): una connessione che richiede solo questi può identificare chi sei e nient’altro. Le autorizzazioni effettive di un’app sono l’intersezione tra gli scope approvati e il tuo ruolo nella console, mai la più ampia delle due. Per creare una sessione di verifica con didit_session_create servono lo scope didit:verification e un ruolo con create:sessions o write:sessions. Il ruolo Developer include create:sessions. Approvare il solo didit:management non consente la creazione di sessioni, anche se il tuo ruolo ha l’autorizzazione richiesta.

Ruoli e autorizzazioni

Il token rilasciato dal server ospitato rappresenta te, quindi l’agente può lavorare su ogni organizzazione di cui fai parte con una singola connessione: gli strumenti inter-app (didit_session_search, didit_analytics, didit_context_get e gli altri strumenti *_search) aggregano automaticamente i dati di tutte. Il tuo ruolo è sempre applicato dal backend di Didit, per ogni organizzazione. Ogni strumento corrisponde a una sola stringa di autorizzazione del backend (ad esempio write:sessions per didit_session_update_status, delete:sessions per didit_session_delete); il riferimento degli strumenti la mostra per ogni strumento. Il server verifica inoltre questa autorizzazione prima di inviare la richiesta, usando le autorizzazioni che la risposta dell’introspezione del token riporta per la tua organizzazione:

In modalità enforce uno strumento che il tuo ruolo non può eseguire viene escluso da tools/list, e chiamarlo comunque restituisce un errore missing_scope che indica l’autorizzazione ("Your role in this organization does not include the permission 'delete:sessions' that didit_session_delete requires.").
In modalità shadow (predefinita del server) ogni strumento viene elencato e la chiamata arriva al backend, che risponde con 403 se il ruolo non ha l’autorizzazione; l’esito viene solo registrato nel registro di audit del server.

In ogni caso, l’MCP non concede mai più di quanto il tuo ruolo nella console già consenta. Un READER può elencare e leggere; un OWNER o un ADMIN può scrivere ed eliminare.

Durata dei token

Un’app approvata ottiene una propria sessione, separata dalla sessione del browser da cui l’hai approvata. Gli access token hanno vita breve; il client li rinnova in modo trasparente con il refresh token (grant_types_supported include refresh_token), e il rinnovo mantiene gli scope dell’app e resta vincolato a quell’app. Se un rinnovo fallisce (ad esempio dopo che hai disconnesso l’app), il client esegue di nuovo Accedi con Didit alla chiamata successiva. Il logout dalla console non disconnette le app collegate, e disconnettere un’app non ti disconnette mai da nessuna parte.

Disconnettere un’app

Dalla console

Impostazioni → Autenticazione → App collegate elenca ogni app che hai approvato, con il nome registrato e le autorizzazioni concesse. Disconnetti interrompe immediatamente l’accesso di quell’app: sia il suo access token sia il suo refresh token smettono di funzionare, e nient’altro viene modificato.

Dall'app (RFC 7009)

Un client può revocare il proprio accesso inviando il token al revocation_endpoint del server di autorizzazione, indicato nei metadati su https://business.didit.me/.well-known/oauth-authorization-server. Come richiesto dall’RFC 7009, una chiamata riuscita restituisce 200 indipendentemente dal fatto che il token fosse ancora valido, quindi la risposta non ti dice mai se un token era valido. Un 503 significa che la revoca non è stata applicata: considera il token ancora valido e riprova.

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

Perché nessuna chiave API? Ogni tool MCP chiama gli endpoint della console con ambito utente (/organization/{org}/application/{app}/…), che autorizzano un token Bearer con privilegi per ruolo e rifiutano x-api-key. Una chiave API dell’applicazione serve per chiamare direttamente la REST API dal tuo backend (ad esempio per creare sessioni), non per questo MCP. didit_org_list_api_keys mostra i metadati delle chiavi con i valori oscurati; il tool che rivela una chiave in chiaro è nascosto sul connettore ospitato.

Connettere ogni client

Ogni client segue lo stesso flusso; cambia solo il modo in cui gli fornisci l’URL.

Claude
Claude Code
Cursor
Client generico

Usa il deep link che la Business Console mostra nella pagina di integrazione. Apre claude.ai con la finestra Add custom connector già compilata:

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

Conferma, quindi completa Accedi con Didit. Claude Desktop usa lo stesso URL in Settings → Connectors → Add custom connector. Dettagli in Connect Claude.

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

Poi esegui /mcp dentro Claude Code per avviare l’accesso tramite browser.

~/.cursor/mcp.json:

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

Cursor si registra da solo e apre il browser al primo utilizzo.

Indirizza qualsiasi client Streamable HTTP con supporto OAuth 2.1 verso https://mcp.didit.me/mcp. Deve:

Eseguire POST /mcp, ricevere 401 e leggere resource_metadata da WWW-Authenticate.
Recuperare https://mcp.didit.me/.well-known/oauth-protected-resource/mcp, poi i metadati del server di autorizzazione su https://business.didit.me/.well-known/oauth-authorization-server.
Registrarsi al registration_endpoint se non ha un client id.
Eseguire il flusso del codice di autorizzazione con PKCE (S256) all’authorization_endpoint, quindi scambiare il codice al token_endpoint.
Inviare Authorization: Bearer <access_token> in ogni POST /mcp.

I client senza supporto OAuth possono passare da npx -y mcp-remote@latest https://mcp.didit.me/mcp, che esegue per loro i passaggi da 1 a 5.

Errori di autenticazione

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 da /mcp significa che il token manca, è scaduto o è stato revocato: il client dovrebbe aggiornarlo o rieseguire Accedi con Didit. Un 403 o un errore missing_scope su un tool specifico significa di solito che il tuo ruolo non ha quell’autorizzazione (ad esempio un READER che tenta una scrittura) oppure che la connessione è stata approvata senza lo scope richiesto da quel tool, non che l’intera connessione sia guasta. Riconnettersi e approvare entrambi gli scope risolve il secondo caso; il primo richiede un cambio di ruolo. Se ogni tool fallisce, controlla Impostazioni → Autenticazione → App collegate nella console: un’app disconnessa lì deve essere approvata di nuovo.

Riferimento dei tool

Cosa fa ogni tool, il suo scope e l’autorizzazione del ruolo.

Avanzate

Ruoli, comportamento tra app e self-hosting.

Guide

Autenticazione

Model Context Protocol (MCP)

SDK web

SDK nativi

SDK server

Integrazioni

Autenticazione MCP di Didit: accedi con Didit (OAuth)

Accedi con Didit

Scope

Ruoli e autorizzazioni

Durata dei token

Disconnettere un’app

Connettere ogni client

Errori di autenticazione

Riferimento dei tool

Avanzate

​Accedi con Didit

​Scope

​Ruoli e autorizzazioni

​Durata dei token

​Disconnettere un’app

​Connettere ogni client

​Errori di autenticazione

Riferimento dei tool

Avanzate

Accedi con Didit

Scope

Ruoli e autorizzazioni

Durata dei token

Disconnettere un’app

Connettere ogni client

Errori di autenticazione