# Collegare Shager a Claude Code: un comando e prepari post per 50 account dal terminale

_2026-08-04 · Aggiungi il server MCP remoto di Shager a Claude Code con claude mcp add e un header bearer, scegli l'ambito, verifica e prepara un primo post multi-account._

Per collegare Shager a Claude Code esegui `claude mcp add --transport http shager https://app.shager.ai/api/mcp --header "Authorization: Bearer shgr_live_..."` e poi controlla `/mcp` all'interno di una sessione. Così registri il server MCP remoto di Shager tramite HTTP in streaming, e Claude Code può subito elencare i tuoi clienti, gli account collegati e i post. Una volta che hai la chiave API, ci vogliono circa due minuti.

Questa guida spiega come ottenere la chiave, come scegliere l'ambito di configurazione giusto, come tenere il segreto fuori da git e qual è il primo compito concreto da far svolgere.

## Cosa ti serve prima di iniziare?

Due cose: Claude Code installato e una chiave API di Shager che inizia con `shgr_live_`.

La chiave si ottiene in due modi. Se hai già un account Shager, una persona del tuo team la crea su https://app.shager.ai/dashboard/agents e sceglie gli ambiti (`read`, `write` e, se serve, `publish`). Se non hai ancora un account, l'agente può registrarsi da solo con una sola chiamata HTTP e ricevere una chiave per l'ambiente di prova. Il procedimento è spiegato in [registrazione autonoma degli agenti e rivendicazione](/it/blog/agent-self-signup-and-claim), e la versione breve si trova su [/auth.md](/auth.md).

Due parole sugli ambiti prima di incollare qualsiasi cosa. Per la prima settimana, concedi a Claude Code solo `read` e `write`. In questo modo può creare clienti, caricare file multimediali e preparare bozze, ma non può programmare né pubblicare nulla. Aggiungerai `publish` più avanti, quando ti fiderai delle bozze che produce.

## Come si aggiunge il server con claude mcp add?

La [documentazione MCP](https://code.claude.com/docs/en/mcp) di Claude Code mostra la forma esatta per un server HTTP remoto con token bearer: `--transport http`, un nome, l'URL e `--header`. Per Shager diventa:

```bash
claude mcp add --transport http shager https://app.shager.ai/api/mcp \
  --header "Authorization: Bearer shgr_live_your_key_here"
```

La documentazione precisa che `claude mcp add` salva la configurazione senza verificare la credenziale. Un errore di battitura nella chiave non dà problemi in questa fase: l'errore arriva dopo, quando il client si collega.

### Quale ambito conviene usare?

Il flag `--scope` stabilisce dove viene salvata la configurazione. Secondo la stessa pagina della documentazione:

| Ambito | Dove viene salvato | Quando usarlo |
|---|---|---|
| `local` (predefinito) | Nella tua configurazione utente, solo per questo progetto | Stai provando Shager in un solo repository |
| `project` | In `.mcp.json` nel repository, condiviso con il team | Tutto il team gestisce i contenuti da questo repository |
| `user` | Nella tua configurazione utente, per tutti i progetti | Vuoi Shager disponibile ovunque apri Claude Code |

Per un'agenzia, di solito la scelta giusta è `user`: la distribuzione dei contenuti non è legata a un singolo codice sorgente.

```bash
claude mcp add --transport http shager --scope user https://app.shager.ai/api/mcp \
  --header "Authorization: Bearer shgr_live_your_key_here"
```

## Come condividi la configurazione senza fare commit della chiave?

Se vuoi l'ambito `project`, così che i colleghi ricevano il server in automatico, non scrivere la chiave in chiaro in `.mcp.json`. Per i server HTTP, Claude Code supporta l'espansione delle variabili d'ambiente in `url` e `headers`, con `${VAR}` o `${VAR:-default}`. Fai commit di questo:

```json
{
  "mcpServers": {
    "shager": {
      "type": "http",
      "url": "https://app.shager.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer ${SHAGER_API_KEY}"
      }
    }
  }
}
```

Poi ognuno esporta la propria chiave nel profilo della shell:

```bash
export SHAGER_API_KEY="shgr_live_your_key_here"
```

Due dettagli della documentazione contano. Se la variabile non è impostata, Claude Code carica comunque la configurazione e invia il testo letterale `${SHAGER_API_KEY}`, con un avviso in `claude mcp list`. Inoltre alcuni nomi di credenziali riservati, come `ANTHROPIC_API_KEY`, negli header remoti vengono espansi di proposito come stringa vuota: usa quindi sempre un nome di variabile tuo. `SHAGER_API_KEY` va benissimo.

Chiavi separate per ogni persona rendono utile anche il registro di audit su https://app.shager.ai/dashboard/agents. Ogni chiamata di un agente viene registrata con la chiave che l'ha eseguita, quindi sai quale sessione ha creato quale bozza.

## Come verifichi che funzioni?

Dalla shell:

```bash
claude mcp list
claude mcp get shager
```

All'interno di una sessione, digita `/mcp`. Un server funzionante risulta collegato. Secondo la documentazione, un server con credenziali errate risulta in errore e il dettaglio riporta lo stato HTTP. Per Shager, un 401 significa che l'header manca o è malformato. Il server si aspetta esattamente `Authorization: Bearer shgr_...`, con la parola Bearer e un solo spazio.

Poi chiedi a Claude qualcosa di semplice e in sola lettura:

```text
Call whoami on shager, then list my workspaces with their channel counts.
```

`whoami` restituisce l'organizzazione e gli ambiti della chiave. Se vedi `read` e `write` ma non `publish`, la configurazione funziona esattamente come previsto.

## Quale dovrebbe essere il primo compito vero?

Non partire con «pubblica qualcosa». Parti da una bozza che metta alla prova le parti di Shager che contano quando si lavora su larga scala. Un buon primo prompt:

```text
In the workspace "Northside Dental", list the channels and the account groups.
Upload this video as media: https://example.com/clips/whitening-30s.mp4
(width 1080, height 1920, duration_ms 30000).
Then create a DRAFT post (no schedule_at) to the group "All locations" as a REEL,
with a caption per channel that mentions the city in that account's name,
first_comment "Book a slot: " plus the cta_url,
cta_url https://northsidedental.example/book, campaign "whitening-oct".
Show me the per-channel captions before you call create_post.
```

Dietro le quinte Claude concatena `list_channels`, `list_groups`, `upload_media_from_url` e `create_post`. In quella chiamata, tre campi fanno il grosso del lavoro.

1. `per_channel` permette a ogni account di avere un testo proprio invece di cinquanta post identici. I duplicati li notano sia i social sia il pubblico, ed è per questo che lo consigliamo in [come evitare i blocchi per spam quando pubblichi su larga scala](/it/blog/avoid-spam-blocks-when-posting-at-scale).
2. `cta_url` riceve un link breve e un tag UTM separati per ogni account, con `utm_content` che identifica l'account. I clic tornano indietro account per account tramite `get_analytics`.
3. Passare larghezza, altezza e `duration_ms` al caricamento permette a Shager di verificare il Reel rispetto alle regole di ogni social prima di mettere qualcosa in coda.

Visto che non è stato passato `schedule_at`, il risultato è una bozza. La controlli nell'app di Shager oppure chiedi a Claude di chiamare `get_post`.

## Come controlli cosa può fare Claude Code?

Claude Code chiede il permesso prima di chiamare i tool MCP, a meno che tu non li abbia autorizzati. I tool MCP si chiamano `mcp__<server>__<tool>`, quindi per Shager vedrai `mcp__shager__create_post`, `mcp__shager__list_posts` e così via. Una lista di autorizzazioni iniziale ragionevole approva i tool di lettura e lascia su richiesta tutto ciò che scrive. Abbinala a una chiave senza `publish` e avrai due freni indipendenti: il client chiede a te, e il server rifiuta comunque di programmare.

Quando sei pronto a programmare, crea una nuova chiave con `publish`, cambia la variabile d'ambiente e tieni la vecchia chiave read/write per le sessioni esplorative. L'API REST e il server MCP di Shager applicano gli stessi ambiti, quindi la regola vale qualunque strada prenda uno script.

## Checklist per la risoluzione dei problemi

| Sintomo | Causa probabile | Soluzione |
|---|---|---|
| `/mcp` risulta in errore, 401 | Nell'header manca `Bearer ` o la chiave è sbagliata | Aggiungi di nuovo il server, oppure controlla che la variabile sia esportata nella shell da cui hai avviato Claude |
| I tool compaiono ma `create_post` con `schedule_at` restituisce 403 | Alla chiave manca `publish`, oppure l'ambiente di prova non è stato rivendicato | È previsto. Crea una bozza, oppure fai aggiungere l'ambito a una persona |
| 429 `rate_limited` | Più di 120 richieste al minuto su una sola chiave | Raggruppa il lavoro: un solo `create_post` copre molti account |
| 422 `rejected` | Una regola del social non è rispettata, per esempio un Reel troppo lungo | Leggi il messaggio: indica l'account e la regola |

## Domande frequenti

### Devo installare qualcos'altro oltre a Claude Code?

No. Shager funziona come server MCP remoto, quindi non ci sono processi locali, container Docker o pacchetti npm da installare. Claude Code comunica direttamente con https://app.shager.ai/api/mcp tramite HTTP in streaming.

### Claude Code può pubblicare senza che io approvi ogni post?

Solo se la chiave che usa ha l'ambito `publish` e l'account è stato rivendicato da una persona. Senza quell'ambito, le chiamate per programmare e pubblicare restituiscono 403, qualunque cosa tenti l'agente. Molti team attivano anche l'approvazione del cliente per ogni area di lavoro, che aggiunge una revisione umana prima della programmazione.

### Shager supporta l'accesso OAuth per Claude Code?

Sì. Il server MCP di Shager supporta l'accesso OAuth per qualsiasi client MCP che lo preveda. Aggiungi il server senza il flag `--header`, esegui `/mcp` e scegli di autenticarti, poi accedi a Shager e approva nel browser. L'header con la chiave API mostrato sopra funziona ancora ed è la scelta migliore per script e macchine su cui nessuno può fare l'accesso.

## Prossimo passo

Quando Claude Code vede i tuoi clienti, il passo naturale successivo è rendere ripetibile la routine invece di riscrivere ogni volta i prompt. La guida su [come creare una skill di Claude per Shager](/it/blog/build-a-claude-skill-for-shager) trasforma il flusso di bozze descritto sopra in un comando `/shager` che tutto il team può usare, e la [pagina sugli agenti](/it/agents) elenca ogni tool ed endpoint, se prima vuoi la mappa completa.

---
Source: https://shager.ai/it/blog/connect-shager-to-claude-code