# Shager in OpenAI Codex: config.toml, bearer_token_env_var e una lista di tool che tiene le bozze al loro posto

_2026-08-20 · 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](https://developers.openai.com/codex/mcp) di OpenAI descrive i server HTTP in streaming configurati con un `url`, più tre modi di autenticarsi tramite header. Il [riferimento della configurazione](https://developers.openai.com/codex/config-reference) 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:

```toml
[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:

```bash
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](https://github.com/openai/codex/blob/main/codex-rs/cli/src/mcp_cmd.rs)):

```bash
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:

```bash
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:

```toml
[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:

```toml
[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:

```text
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](/it/blog/utm-per-account-lead-attribution).

## 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](/it/blog/skill-weekly-distribution-routine).

## 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](/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](https://app.shager.ai/api/v1/openapi.json) 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](/it/blog/shager-rest-api-quickstart) 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.

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