Shager in OpenAI Codex: config.toml, bearer_token_env_var e una lista di tool che tiene le bozze al loro posto
Configura il server MCP remoto di Shager in Codex CLI con config.toml o codex mcp add, leggi la chiave da una variabile, limita i tool e crea una prima bozza.
Per collegare Shager a Codex CLI di OpenAI, aggiungi una tabella [mcp_servers.shager] a ~/.codex/config.toml con url = "https://app.shager.ai/api/mcp" e bearer_token_env_var = "SHAGER_API_KEY", poi esporta la tua chiave shgr_live_ in quella variabile. Codex parla nativamente HTTP in streaming e invia la chiave come token bearer, quindi non servono ponti né processi locali. Puoi anche fare tutto in una riga con codex mcp add shager --url ... --bearer-token-env-var SHAGER_API_KEY.
Il resto della guida spiega come farlo senza pentirsene: tenere la chiave fuori dal file, limitare i tool di Shager che Codex può chiamare e scegliere un primo compito che dimostri che il collegamento funziona.
Cosa supporta Codex per i server MCP remoti?
La documentazione MCP di Codex di OpenAI descrive i server HTTP in streaming configurati con un url, più tre modi di autenticarsi tramite header. Il riferimento della configurazione li definisce così:
| Chiave | Cosa fa |
|---|---|
bearer_token_env_var |
Nome di una variabile d'ambiente il cui valore viene inviato come token bearer |
http_headers |
Header statici inclusi in ogni richiesta |
env_http_headers |
Header i cui valori vengono letti da variabili d'ambiente |
Shager si aspetta Authorization: Bearer shgr_live_..., cioè esattamente ciò che produce bearer_token_env_var. È l'opzione da usare.
Opzione A: modificare config.toml
Apri ~/.codex/config.toml e aggiungi:
[mcp_servers.shager]
url = "https://app.shager.ai/api/mcp"
bearer_token_env_var = "SHAGER_API_KEY"
Poi metti la chiave nel profilo della shell, non nel TOML:
export SHAGER_API_KEY="shgr_live_your_key_here"
Nota che la configurazione contiene il nome della variabile, non la chiave. Puoi quindi fare commit dello snippet o condividerlo senza problemi, e ogni collega usa la propria chiave. Le chiavi separate per persona ripagano più avanti, perché il registro di audit di Shager su https://app.shager.ai/dashboard/agents registra ogni chiamata con la chiave che l'ha eseguita.
Opzione B: codex mcp add
La CLI scrive la stessa tabella al posto tuo. Il codice sorgente di Codex per codex mcp add definisce --url per i server HTTP in streaming e un flag --bearer-token-env-var che lo richiede (mcp_cmd.rs su GitHub):
codex mcp add shager \
--url https://app.shager.ai/api/mcp \
--bearer-token-env-var SHAGER_API_KEY
Se la tua versione installata è diversa, fa fede codex mcp add --help.
Controlla il risultato:
codex mcp list
Nella TUI di Codex, /mcp mostra i server attivi e i loro tool.
Conviene usare http_headers?
Si può, ma è meglio di no. http_headers = { "Authorization" = "Bearer shgr_live_..." } funziona, ma mette una credenziale valida in un file di testo semplice che tende a finire copiato nei repository dei dotfile. Se ti serve un header diverso dal token bearer, env_http_headers associa il nome di un header al nome di una variabile d'ambiente:
[mcp_servers.shager]
url = "https://app.shager.ai/api/mcp"
env_http_headers = { "Authorization" = "SHAGER_AUTH_HEADER" }
In questa forma la variabile deve contenere il valore completo, schema incluso: export SHAGER_AUTH_HEADER="Bearer shgr_live_...". Per Shager, bearer_token_env_var è più semplice e fa la stessa cosa.
Come limiti quello che Codex può fare in Shager?
È la parte che la maggior parte delle guide salta. Codex ti permette di filtrare i tool di un server con enabled_tools (una lista di consentiti) e disabled_tools (una lista di esclusi applicata dopo), entrambi documentati nel riferimento della configurazione. Abbinali agli ambiti delle chiavi di Shager e ottieni due livelli che, in caso di dubbio, bloccano.
Un profilo per le bozze che può leggere tutto e creare bozze, ma non può programmare, annullare né creare link di collegamento:
[mcp_servers.shager]
url = "https://app.shager.ai/api/mcp"
bearer_token_env_var = "SHAGER_API_KEY"
enabled_tools = [
"whoami",
"list_workspaces",
"list_channels",
"list_groups",
"upload_media_from_url",
"create_post",
"get_post",
"list_posts",
"get_analytics",
]
tool_timeout_sec = 120
create_post resta nella lista perché, senza schedule_at, salva solo una bozza. Se alla chiave manca anche l'ambito publish, Shager rifiuta con un 403 qualsiasi create_post che includa schedule_at: nemmeno un modello molto creativo riesce a far passare di nascosto un post programmato.
L'aumento di tool_timeout_sec c'è perché upload_media_from_url scarica il file lato server, e un video verticale pesante può richiedere più dei 60 secondi predefiniti indicati nel riferimento.
Un primo compito che vale la pena eseguire
Comincia con un prompt che tocca diversi tool e lascia dietro di sé solo una bozza:
Use the shager MCP server.
1. whoami, then list_workspaces.
2. In workspace "Lakeside Realty", list_channels and list_groups.
3. upload_media_from_url https://example.com/media/open-house.jpg
4. create_post as a draft to group "All agents" with a different caption per
channel (per_channel), mentioning each agent's neighborhood from the channel
name. cta_url https://lakesiderealty.example/open-house, campaign
"open-house-oct", first_comment "Details and RSVP: " followed by the link.
5. get_post and print a table of channel, network, format and state.
Cosa dovresti vedere: un post in stato DRAFT con una destinazione per ogni account, ciascuna con il formato già risolto per quel social. In Shager ogni account riceve il proprio link breve e i propri tag UTM per il cta_url, con utm_content che indica l'account: è questo che più avanti rende possibile l'attribuzione per account. I dettagli sono in attribuzione dei contatti per account.
Codex può farlo girare senza una persona alla tastiera?
Codex ha una modalità non interattiva, codex exec, per script e CI. Il comportamento delle approvazioni dei tool MCP in un'esecuzione senza interfaccia è cambiato da una versione all'altra, quindi fai una prova a vuoto sulla tua versione prima di metterla su un timer. Per un lavoro che deve girare ogni settimana senza supervisione, molti team saltano lo strato di chat e chiamano l'API REST di Shager da un breve script, che non ha richieste di approvazione su cui bloccarsi. Qualunque strada tu scelga, dai al lavoro una chiave tutta sua, tieni stretta la lista dei tool e decidi consapevolmente se quella chiave deve avere publish. Una routine costruita attorno a queste scelte è descritta in la routine settimanale di distribuzione.
Risoluzione dei problemi
| Cosa vedi | Causa | Soluzione |
|---|---|---|
401 unauthorized |
Variabile non esportata nella shell da cui hai avviato Codex | echo $SHAGER_API_KEY nello stesso terminale, poi riavvia Codex |
Tool assenti da /mcp |
Nome non presente in enabled_tools, oppure elencato in disabled_tools |
Controlla l'ortografia con l'elenco dei tool su /it/agents |
403 sandbox_unclaimed |
La chiave viene dalla registrazione autonoma di un agente e nessuna persona l'ha rivendicata | Manda il claim_url a una persona |
403 forbidden sulla programmazione |
Alla chiave manca publish |
Previsto, per una chiave da bozze |
429 rate_limited |
Oltre 120 richieste al minuto per chiave | Usa i gruppi e un solo create_post invece di una chiamata per account |
Domande frequenti
Codex ha bisogno di OAuth per comunicare con Shager?
No. Codex supporta token bearer presi da una variabile d'ambiente, e Shager accetta la chiave API in questo modo. Il server MCP di Shager supporta anche l'accesso OAuth, e Codex supporta anche i server OAuth: se preferisci non gestire una chiave, puoi semplicemente accedere.
La configurazione di Shager cambia nell'estensione di Codex per l'IDE?
Secondo la documentazione MCP di OpenAI, l'app desktop di ChatGPT, Codex CLI e l'estensione per l'IDE condividono questa configurazione, quindi la stessa tabella in ~/.codex/config.toml vale per tutti. Assicurati che la variabile d'ambiente sia visibile al processo dell'editor: su macOS può voler dire avviare l'editor da un terminale.
Posso puntare Codex all'API REST invece che a MCP?
Sì, se stai scrivendo codice invece di chattare. Il documento OpenAPI descrive le stesse operazioni dei tool MCP, con gli stessi ambiti e limiti.
Prossimo passo
Con Codex collegato, prendi confidenza con le operazioni prima di automatizzare qualsiasi cosa. Il quickstart dell'API REST percorre l'intera sequenza, dall'area di lavoro al post tracciato, con curl e Python, e ti aiuta anche a leggere cosa fa Codex quando chiama i tool MCP.
