# Connetti un'app AI

> Connetti Claude, ChatGPT, Cursor, VS Code o qualsiasi client MCP a TradeCatalog con il tuo login.

TradeCatalog esegue un server [Model Context Protocol](https://modelcontextprotocol.io) (MCP) remoto. Collegalo alla tua app AI e fai domande come:

- "Quanto paga Oakfield Joinery per 20 scatole di HX-8510?"
- "Ci sono nuovi ordini oggi?"
- "Chi ha modificato lo sconto di Brookside e quando?"
- "Trova un bullone esagonale in zinco, M10, e il mio prezzo per esso." (come acquirente)

## Come funziona

| Impostazione    | Valore                                                                                            |
| --------------- | ------------------------------------------------------------------------------------------------- |
| URL del server  | `https://tradecatalog.app/mcp`                                                                    |
| Trasporto       | HTTP streaming                                                                                    |
| Accesso         | OAuth 2.1: ti puoi autenticare con il tuo normale login TradeCatalog e scegliere **Consenti**     |
| Accesso         | Accesso in lettura, con accesso opzionale in scrittura con revisione per modifiche significative. |
| Chi agisce come | Tu. Vedrà esattamente ciò che puoi vedere in TradeCatalog.                                        |

- **Personale** vede i dati consentiti dal loro ruolo e ambito clienti. Il personale di vendita può coprire solo clienti o aree assegnati; modifiche al catalogo, prezzi, ordini e squadra richiedono sempre la relativa autorizzazione.
- **Acquirenti** vedono i fornitori da cui acquistano, con i loro propri prezzi e i loro propri ordini solo.

Le invita di squadra, le impostazioni dello spazio di lavoro e l'accesso API seguono le autorizzazioni attuali del personale del fornitore. La cancellazione dello spazio di lavoro rimane solo per il proprietario. Gli acquirenti selezionano il proprio account cliente per ogni ordine. Le connessioni esistenti rimangono in sola lettura fino a quando non vengono riautorizzate.

Ogni chiamata di strumento viene controllata con le stesse regole dell'app. Vedere [Strumenti MCP](/docs/mcp/tools) per sapere cosa fa ogni strumento.

## Competenze del flusso di lavoro

Il plugin TradeCatalog include dieci competenze specifiche con la sua connessione MCP. Ogni descrizione di competenza indica quando si applica il flusso di lavoro all'app AI; le sue istruzioni spiegano quali strumenti utilizzare, cosa leggere per primo e come gestire le conferme e i risultati incompleti.

| Competenza                | Quando utilizzarla                                                                                                         |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `tradecatalog`            | Connetti, crea un'area di lavoro del fornitore o seleziona un fornitore e un account cliente.                              |
| `tradecatalog-catalogue`  | Crea, modifica, nasconde, mostra e organizza prodotti o apri gli upload dei media del prodotto.                            |
| `tradecatalog-pricing`    | Spiega i prezzi concordati e modifica i termini, o crea e pubblica modifiche ai prezzi di listino.                         |
| `tradecatalog-imports`    | Controlla e importa righe di prodotti, account clienti o prezzi concordati.                                                |
| `tradecatalog-customers`  | Onboard dei clienti, invita gli acquirenti e gestisci l'accesso o le liste di prodotti approvati.                          |
| `tradecatalog-orders`     | Cerca i prezzi degli acquirenti, prepara o ripeti un ordine, scarica un elenco dei prezzi autorizzati o traccia un ordine. |
| `tradecatalog-fulfilment` | Controlla gli ordini dei fornitori e conferma, invia, completa o annulla.                                                  |
| `tradecatalog-updates`    | Leggi gli aggiornamenti degli acquirenti o pubblica annunci dei fornitori con scelta esplicita del momento e dell'email.   |
| `tradecatalog-workspace`  | Gestisci le impostazioni aziendali, le invita del personale e i trasferimenti autorizzati di esportazione o API.           |
| `tradecatalog-support`    | Leggi, prepara o invia una richiesta di supporto del fornitore o un follow-up a Happy Webs.                                |

Altri agenti possono scoprire le stesse guide dal [indice delle competenze pubbliche](https://tradecatalog.app/.well-known/agent-skills/index.json). Le competenze guidano il flusso di lavoro; il server controlla comunque l'accesso al conto e richiede la conferma con accesso per modifiche significative.

## Registrati e paga con un agente

Puoi connetterti prima di avere un'area di lavoro. La connessione apre la pagina di accesso di TradeCatalog, dove un nuovo indirizzo email crea il tuo accesso dopo che lo hai verificato. Completa la verifica lì, quindi torna alla tua app AI. Non condividere mai codici di accesso o dettagli di pagamento in chat.

Chiedi all'agente di creare la tua area di lavoro del fornitore. Ti chiede il nome della tua azienda, la valuta dei prodotti, il fuso orario e il paese, quindi utilizza `create_workspace` per la tua conferma. La tua area di lavoro inizia con un periodo di prova Pro di 14 giorni senza carta. Non è una sottoscrizione a pagamento. Quando finisce il periodo di prova torna a Free, fino a 100 prodotti, a meno che non ti aggiorni.

Per gli agenti i cui host permettono la fatturazione per abbonamento al software, connettiti a **`https://tradecatalog.app/mcp/account`**. Utilizza lo stesso login TradeCatalog, gli stessi ambiti OAuth e le stesse appartenenze al workspace, con tutti gli strumenti ordinari più `open_billing`. Quando chiedi di pagare o gestire il tuo abbonamento, questo strumento riservato agli owner apre la pagina di fatturazione sicura del workspace. Scegli la fatturazione mensile o annuale e conferma il pagamento su Stripe. I sottoscrittori esistenti possono gestire il loro abbonamento lì. L'agente può verificare `get_settings` successivamente; aprire un link non è prova che il pagamento sia stato completato.

I plugin di ChatGPT utilizzano **`https://tradecatalog.app/mcp`**, che non espone strumenti di fatturazione. Le [linee guida per i plugin](https://developers.openai.com/plugins/plugin-guidelines) di OpenAI escludono attualmente la vendita di abbonamenti software e la promozione di aggiornamenti. La registrazione gratuita e la creazione di spazi di lavoro sono disponibili tramite questa connessione. Gli agenti possono preparare le richieste di ordine commerciale. I pagamenti opzionali per i clienti richiedono che l'acquirente apra la pagina dell'ordine autenticato, approvi l'esatto addebito confermato dal fornitore e completi Stripe Checkout. L'approvazione di un ordine da parte dell'agente non è mai un'autorizzazione al pagamento.

## Claude (web, desktop e mobile)

1. Apri **Impostazioni**, poi **Connettori**, e scegli **Aggiungi un connettore personalizzato**.
2. Assegnagli il nome “TradeCatalog” e incolla `https://tradecatalog.app/mcp`.
3. Scegli **Connetti**. Effettua l'accesso a TradeCatalog con il tuo codice email e scegli **Consenti**.

I connettori aggiunti sul web appaiono anche in Claude Desktop e nelle app mobili. Su piani Team ed Enterprise, un owner potrebbe dover aggiungere il connettore per l'organizzazione prima.

## Claude Code

```bash
claude mcp add --transport http tradecatalog https://tradecatalog.app/mcp
```

Esegui poi `/mcp` in Claude Code e scegli **tradecatalog** per accedere.

## ChatGPT

1. Apri **Impostazioni**, poi **Apps & Connectors**. Se necessario per il tuo piano, attiva **Modalità sviluppatore** sotto **Avanzate**.
2. Crea un connettore con l'URL `https://tradecatalog.app/mcp` e autenticazione OAuth.
3. Effettua l'accesso a TradeCatalog e scegli **Consenti**.

## Cursor

Aggiungi questo a `~/.cursor/mcp.json` (o `.cursor/mcp.json` in un progetto):

```json
{
  "mcpServers": {
    "tradecatalog": { "url": "https://tradecatalog.app/mcp" }
  }
}
```

Cursor apre la pagina di accesso a TradeCatalog la prima volta che lo usi.

## VS Code

Aggiungi questo a `.vscode/mcp.json`:

```json
{
  "servers": {
    "tradecatalog": { "type": "http", "url": "https://tradecatalog.app/mcp" }
  }
}
```

## Altri client

Qualsiasi client che supporta MCP remoto tramite HTTP streaming con OAuth funziona. Per i client che eseguono solo server locali (stdio), usa il ponte `mcp-remote`:

```json
{
  "mcpServers": {
    "tradecatalog": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://tradecatalog.app/mcp"]
    }
  }
}
```

Vuoi creare il tuo client? Consulta [OAuth per client MCP](/docs/mcp/oauth).

## Disconnetti un'app

Visualizza ogni app AI che hai approvato e disconnettila, su [tradecatalog.app/oauth/connections](/oauth/connections). Rimuovendo il connettore nella tua app AI, questa non potrà più utilizzarlo. Disconnetterti qui revoca anche il suo accesso sul nostro lato, immediatamente.

## MCP o REST API?

|                             | MCP                                                   | REST API                                    |
| --------------------------- | ----------------------------------------------------- | ------------------------------------------- |
| Per                         | Persone che chiacchierano in un'app AI                | I tuoi sistemi e script                     |
| Si autentica come           | Ogni persona, con il proprio login                    | Il workspace, con una chiave API dell'owner |
| I compratori possono usarlo | Sì, con i loro prezzi                                 | No                                          |
| Può modificare i dati       | Sì, con lo scope di scrittura e modifiche revisionate | Sì, con una chiave di lettura e scrittura   |
| Configurato da              | Ogni persona, nella sua app AI                        | L'owner, nelle Impostazioni                 |
| Documentazione              | [Strumenti](/docs/mcp/tools)                          | [REST API](/docs/api)                       |