Connettori claude.ai e ChatGPT

Dove si trova nell'amministrazione: System › Settings › API & AI agents (/agent/keys), scheda Connected apps. La schermata di consenso si apre su /agent/consent quando un connettore richiede l'accesso (non si trova nel menu).

Descrizione

Le app di IA web non possono leggere una chiave dal tuo disco. Si connettono tramite OAuth: aggiungi l'URL MCP del pannello, l'app ti reindirizza alla tua amministrazione per accedere, scegli cosa l'app può fare e per quanto tempo, e l'app riceve token di breve durata. Nessuna chiave viene copiata o incollata. Puoi interrompere l'app in qualsiasi momento.

Usa questa funzione per i connettori personalizzati di claude.ai, i connettori in modalità sviluppatore di ChatGPT e qualsiasi altro client MCP che supporta OAuth con registrazione dinamica del client. Gli strumenti da riga di comando possono usare lo stesso flusso, ma una chiave API amministrativa risulta più semplice per essi.

Requisiti

Elemento	Requisito
URL	https://cloud.example.com/mcp/admin, raggiungibile da Internet (i server del fornitore vi si connettono).
Reverse proxy	Se metti il tuo proxy davanti al pannello, questo deve inoltrare i percorsi /mcp/admin, /oauth-admin/ e /.well-known/ al pannello.
Tu	Connesso all'amministrazione di NexCMP nello stesso browser che usi per la schermata di consenso.
Client	Supporta MCP su Streamable HTTP, OAuth 2.1 con PKCE (S256) e registrazione dinamica del client.

Connessione

1. Nell'app di IA, aggiungi un connettore MCP personalizzato e incolla https://cloud.example.com/mcp/admin. In claude.ai questo si trova nelle impostazioni dei connettori (aggiungi connettore personalizzato); in ChatGPT si trova in modalità sviluppatore (aggiungi un connettore MCP, autenticazione OAuth).
2. Scegli Sign in (o "Connect") nell'app. Il tuo browser apre la schermata di consenso dell'amministrazione di NexCMP. Se non hai effettuato l'accesso, fallo prima; la schermata continuerà subito dopo.
3. Leggi la scheda: "Example AI app wants to manage this NexCMP admin" (il nome dell'app che sta richiedendo l'accesso), con l'indirizzo a cui verrai reindirizzato.
4. Spunta i permessi da concedere. Quelli richiesti dall'app sono pre-spuntati; se non ne ha richiesti, solo admin:read è spuntato. Vedi Scopes.
5. Scegli la durata della connessione: 7, 30 o 90 giorni (predefinito 30).
6. Fai clic su Allow. Il browser torna all'app, che ora risulta connessa. Fai clic su Deny per rifiutare.

::: important Scegli i permessi come faresti per una chiave Concedi l'insieme minimo necessario per svolgere il compito. Azioni relative a denaro, eliminazione e sicurezza si fermano comunque a un'anteprima e richiedono la tua approvazione, ma una connessione con settings:write può comunque modificare il tuo brand e la tua email. :::

Gestione e revoca

Apri System › Settings › API & AI agents › Connected apps. La tabella elenca ogni app che hai connesso: applicazione, permessi, momento della connessione, scadenza e ultimo utilizzo.

Per interrompere un'app, fai clic su Revoke e conferma. I suoi token smettono di funzionare immediatamente; l'app dovrà ripetere la procedura di consenso per riconnettersi.

Come funziona il flusso

Passaggio	Dettaglio
Rilevamento	L'app legge /.well-known/oauth-protected-resource/mcp/admin e poi /.well-known/oauth-authorization-server/oauth-admin. L'emittente è https://cloud.example.com/oauth-admin.
Registrazione	L'app registra se stessa (POST /oauth-admin/register, RFC 7591). Sono supportati solo i client pubblici (nessun segreto client). L'indirizzo di reindirizzamento deve essere https, oppure http sullo stesso computer (loopback).
Autorizzazione	GET /oauth-admin/authorize con metodo PKCE S256. Un parametro resource, se inviato, deve corrispondere all'URL /mcp/admin di questo pannello. La richiesta è valida per 10 minuti ed è associata al browser che l'ha avviata.
Consenso	Scegli gli ambiti (scope) e la durata (sopra). Il codice di autorizzazione è valido per 60 secondi e funziona una sola volta.
Token	POST /oauth-admin/token restituisce un token di accesso (un ak_o... chiave, valido 1 ora o fino alla fine della connessione, a seconda di quale evento si verifichi per primo) e un token di aggiornamento (akr_...). Ogni aggiornamento restituisce un nuovo token di aggiornamento; quello vecchio smette di funzionare. La connessione termina dopo i giorni scelti.
Revoca	Revoke in App connesse, oppure l'app chiama POST /oauth-admin/revoke (RFC 7009).

Il token di accesso si comporta come una chiave amministrativa con gli ambiti concessi: stesse regole di ambito, conferma, limite di frequenza e registro attività. Le sue chiamate compaiono nella scheda Activity.

Verifica

1. Nell'app, chiedi "run system_health" (o "what tools do you have?"). L'app elenca gli strumenti consentiti dai tuoi ambiti (the tool list).
2. Apri Connected apps: Last used si aggiorna.
3. Apri Activity: le chiamate sono elencate con il nome dell'app e mcp.

Limiti e note

• Se l'app chiede nuovamente di effettuare l'accesso dopo un'ora, è normale quando un client non esegue il refresh; riconnettiti.
• Un token di refresh utilizzato due volte viene considerato rubato: l'intera connessione viene revocata. Riconnettiti dall'app.
• Un codice di autorizzazione utilizzato due volte viene rifiutato (invalid_grant) e i token già emessi a partire da esso vengono revocate.
• L'accesso OAuth non concede mai più di quanto consentito dalle regole di ambito: what a key can never do si applica anche alle app connesse.
• I vendor modificano i propri menu e le funzionalità supportate. Se l'app di un vendor non offre connettori personalizzati sul tuo piano, usa una admin API key con un client desktop o a riga di comando.

Troubleshooting

Sintomo	Causa	Soluzione
La schermata di consenso mostra "Wrong browser"	La richiesta è stata avviata in un browser diverso da quello in cui hai effettuato l'accesso	Riavvia la connessione dall'app AI nello stesso browser.
La schermata di consenso indica che la richiesta è scaduta o mancante	Sono trascorsi più di 10 minuti oppure il link è stato aperto due volte	Riavvia la connessione dall'app AI.
Pagina "Unknown client" o "redirect address does not match"	La registrazione dell'app non è aggiornata oppure utilizza un indirizzo di reindirizzamento non registrato	Rimuovi il connettore nell'app e aggiungilo di nuovo.
invalid_target	Il resource inviato non corrisponde all'URL /mcp/admin di questo pannello	Usa l'URL esatto mostrato nella scheda Connect an AI.
invalid_request su PKCE	Il client non invia code_challenge_method=S256	Usa un client che supporta OAuth 2.1 con PKCE.
L'app si connette ma una chiamata restituisce insufficient_scope	Non hai selezionato quell'ambito	Revoca la connessione e connettiti di nuovo selezionando l'ambito.
L'app non riesce a raggiungere l'URL	DNS, TLS o il reverse proxy bloccano /mcp/admin, /oauth-admin/ o /.well-known/	Verifica le regole del proxy.