# OAuth per i clienti MCP

> Come i clienti MCP scoprono, registrano e ottengono token per il server TradeCatalog MCP con OAuth 2.1.

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](/docs/mcp).

TradeCatalog segue la specifica di autorizzazione [MCP](https://modelcontextprotocol.io/specification/latest/basic/authorization): OAuth 2.1 con PKCE, metadati delle risorse protette (RFC 9728) e metadati del server di autorizzazione (RFC 8414).

## Endpoint

| Cosa                                  | URL                                                                 |
| ------------------------------------- | ------------------------------------------------------------------- |
| Server MCP (risorsa protetta)         | `https://tradecatalog.app/mcp`                                      |
| Metadati della risorsa protetta       | `https://tradecatalog.app/.well-known/oauth-protected-resource/mcp` |
| Metadati del server di autorizzazione | `https://tradecatalog.app/.well-known/oauth-authorization-server`   |
| Endpoint di autorizzazione            | `https://tradecatalog.app/oauth/authorize`                          |
| Endpoint del token                    | `https://tradecatalog.app/oauth/token`                              |
| Registrazione client dinamica         | `https://tradecatalog.app/oauth/register`                           |
| App connesse (per le persone)         | `https://tradecatalog.app/oauth/connections`                        |

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](/docs/mcp#sign-up-and-pay-with-an-agent).

## Ambito

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](/docs/mcp/tools).

## Flusso di scoperta

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.

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

```json
{
  "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 client

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.

## Autorizzazione

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:

```http
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ò approvare

- 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](/docs/api) 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.

## Trasporto

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

## Revoca

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

## Pubblicato anche

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