OAuth per i clienti MCP

Questa pagina è per le persone che sviluppano un client MCP o risolvono problemi di connessione. Se desideri solo connettere Claude o ChatGPT, consulta Connetti un'app AI.

TradeCatalog segue la specifica di autorizzazione MCP: OAuth 2.1 con PKCE, metadati delle risorse protette (RFC 9728) e metadati del server di autorizzazione (RFC 8414).

EndpointCollegamento a questa sezione#

I metadati della risorsa protetta si trovano all'indirizzo specifico del percorso per /mcp, come descritto dal RFC 9728 per una risorsa con un percorso. Non c'è nulla in modo deliberato a /.well-known/oauth-protected-resource da solo.

La connessione opzionale /mcp/account aggiunge un passaggio sicuro per la fatturazione proprietaria per gli host degli agenti che consentono la fatturazione abbonamento software. È un discendente della stessa risorsa protetta /mcp: utilizzare i metadati sopra e resource=https://tradecatalog.app/mcp durante l'autorizzazione o la richiesta di token. La registrazione, il consenso OAuth e l'accesso allo spazio di lavoro utilizzano lo stesso account. I plugin ChatGPT si connettono a /mcp; consulta registrazione e fatturazione.

AmbitoCollegamento a questa sezione#

Richiedi tradecatalog:read per le ricerche. Richiedi tradecatalog:read tradecatalog:write per preparare anche modifiche. La pagina del consenso descrive l'accesso richiesto. I permessi esistenti in sola lettura non ottengono mai automaticamente l'accesso in scrittura. I ruoli e le restrizioni di fatturazione vengono riconfermati quando si propongono e si approvano azioni. Le scritture conseguenti richiedono una conferma unica nel cartoncino della chat, o nella pagina di revisione con accesso utente autenticato per i clienti senza cartoncini; consulta Strumenti.

Flusso di scopertaCollegamento a questa sezione#

1. Il client chiama https://tradecatalog.app/mcp senza un token.
2. Il server risponde con 401 Unauthorized con un'intestazione WWW-Authenticate: Bearer che punta ai metadati della risorsa protetta.
3. Il client legge i metadati della risorsa protetta per trovare il server di autorizzazione, https://tradecatalog.app.
4. Il client legge i metadati del server di autorizzazione per gli endpoint sopra.

curl https://tradecatalog.app/.well-known/oauth-protected-resource/mcp

{
  "resource": "https://tradecatalog.app/mcp",
  "authorization_servers": ["https://tradecatalog.app"],
  "scopes_supported": ["tradecatalog:read", "tradecatalog:write"],
  "bearer_methods_supported": ["header"],
  "resource_name": "TradeCatalog MCP server"
}

Registrazione del clientCollegamento a questa sezione#

Usa una delle seguenti opzioni:

• Documenti dei metadati dell'ID client (preferito): utilizza un URL https che controlli come client_id, che fornisce i metadati del tuo client. Le persone che approvano la connessione vedono l'host di quel URL come editore.
• Registrazione client dinamica (RFC 7591) su /oauth/register.

Chiunque può registrare un client con qualsiasi nome, quindi la pagina di approvazione mostra alle persone dove viene inviato l'approvazione (l'host di reindirizzamento) e, per gli ID client URL, l'editore. Il nome da solo è contrassegnato come non verificato.

AutorizzazioneCollegamento a questa sezione#

Utilizza il flusso del codice di autorizzazione con PKCE (S256):

1. Invia il browser della persona a /oauth/authorize con response_type=code, client_id, redirect_uri, code_challenge, code_challenge_method=S256, state e scope=tradecatalog:read.
2. Se non è autenticato, TradeCatalog chiede loro di effettuare l'accesso con un codice inviato via email (o Google o Microsoft, se abilitati), quindi li rimanda indietro.
3. Vedono quale applicazione sta chiedendo, l'account con cui sono autenticati e cosa può fare, quindi scelgono Consenti o Rifiuta.
4. Consenti reindirizza al tuo redirect_uri con code e state. Rifiuta reindirizza con error=access_denied.
5. Scambia il codice su /oauth/token con il tuo code_verifier. Ottieni un token di accesso e un token di aggiornamento.

Invia il token di accesso in ogni richiesta MCP:

POST /mcp HTTP/1.1
Host: tradecatalog.app
Authorization: Bearer <access token>
Content-Type: application/json
Accept: application/json, text/event-stream

I token di accesso hanno una durata breve. Utilizza il token di aggiornamento su /oauth/token per ottenerne uno nuovo.

Chi può approvareCollegamento a questa sezione#

• Qualsiasi utente di TradeCatalog autenticato: personale fornitore o acquirenti.
• Non visitatori demo (sessioni ospite). Vengono inviati a effettuare l'accesso correttamente.
• Non esiste un modo per creare un account attraverso questo flusso, né accesso esclusivo macchina (credenziali client). Per l'accesso server-to-server, utilizzare l'API REST con una chiave API.

Il grant include solo l'identità della persona. Ogni chiamata al tool riconferma ciò che possono vedere, quindi se perdono l'accesso a uno spazio di lavoro, l'app AI lo perde anche lei.

TrasportoCollegamento a questa sezione#

Il server è stateless HTTP Streamable. Non emette ID sessione; ogni richiesta è autonoma e risponde con JSON invece di un flusso di eventi.

RevocaCollegamento a questa sezione#

Le persone vedono e disconnettono le app approvate su /oauth/connections. Disconnettere revoca immediatamente il grant e i suoi token.

Pubblicato ancheCollegamento a questa sezione#

• /auth.md: un breve riepilogo di questa pagina per gli agenti.
• /.well-known/mcp/server-card.json: la scheda del server MCP con l'elenco degli strumenti.