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

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, e la versione breve si trova su /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.

Scorri di lato per vedere tutto il diagramma

Come si aggiunge il server con claude mcp add?

La documentazione 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:

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.

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:

{
  "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:

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:

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:

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.

Scorri di lato per vedere tutto il diagramma

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:

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.
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 trasforma il flusso di bozze descritto sopra in un comando /shager che tutto il team può usare, e la pagina sugli agenti elenca ogni tool ed endpoint, se prima vuoi la mappa completa.