# Shager dans OpenAI Codex : config.toml, bearer_token_env_var et une liste d'outils qui garde les brouillons en brouillon

_2026-08-20 · Configurez le serveur MCP de Shager dans Codex CLI via config.toml ou codex mcp add, lisez la clé dans une variable, limitez les outils, créez un brouillon._

Pour connecter Shager à Codex CLI d'OpenAI, ajoutez une table `[mcp_servers.shager]` dans `~/.codex/config.toml` avec `url = "https://app.shager.ai/api/mcp"` et `bearer_token_env_var = "SHAGER_API_KEY"`, puis exportez votre clé `shgr_live_` dans cette variable. Codex parle nativement le HTTP streamable et envoie la clé comme jeton bearer : ni passerelle ni processus local ne sont nécessaires. Vous pouvez aussi tout faire en une ligne avec `codex mcp add shager --url ... --bearer-token-env-var SHAGER_API_KEY`.

La suite de ce guide explique comment le faire sans le regretter : garder la clé hors du fichier, limiter les outils Shager que Codex peut appeler, et choisir une première tâche qui valide le branchement.

## Que prend en charge Codex pour les serveurs MCP distants ?

La [documentation MCP de Codex](https://developers.openai.com/codex/mcp) d'OpenAI décrit les serveurs HTTP streamable configurés avec une `url`, ainsi que trois façons de s'authentifier par en-têtes. La [référence de configuration](https://developers.openai.com/codex/config-reference) les définit :

| Clé | Rôle |
|---|---|
| `bearer_token_env_var` | Nom d'une variable d'environnement dont la valeur est envoyée comme jeton bearer |
| `http_headers` | En-têtes fixes ajoutés à chaque requête |
| `env_http_headers` | En-têtes dont les valeurs sont lues dans des variables d'environnement |

Shager attend `Authorization: Bearer shgr_live_...`, ce que produit précisément `bearer_token_env_var`. C'est l'option à retenir.

## Option A : modifier config.toml

Ouvrez `~/.codex/config.toml` et ajoutez :

```toml
[mcp_servers.shager]
url = "https://app.shager.ai/api/mcp"
bearer_token_env_var = "SHAGER_API_KEY"
```

Placez ensuite la clé dans le profil de votre shell, pas dans le TOML :

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

La configuration contient le nom de la variable, pas la clé elle-même. Vous pouvez donc committer ou partager l'extrait sans crainte, et chaque collègue fournit sa propre clé. Une clé par personne s'avère payante par la suite, car le journal d'audit de Shager sur https://app.shager.ai/dashboard/agents enregistre chaque appel avec la clé qui l'a émis.

## Option B : codex mcp add

La CLI écrit la même table à votre place. Le code source de `codex mcp add` définit `--url` pour les serveurs HTTP streamable et une option `--bearer-token-env-var` qui l'exige ([mcp_cmd.rs sur 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
```

Si votre version installée diffère, c'est `codex mcp add --help` qui fait foi.

Vérifiez le résultat :

```bash
codex mcp list
```

Dans l'interface TUI de Codex, `/mcp` affiche les serveurs actifs et leurs outils.

## Faut-il plutôt utiliser http_headers ?

C'est possible, mais déconseillé. `http_headers = { "Authorization" = "Bearer shgr_live_..." }` fonctionne, mais place un identifiant actif dans un fichier texte en clair, qui a tendance à finir copié dans des dépôts de dotfiles. Si vous avez besoin d'un autre en-tête que le jeton bearer, `env_http_headers` associe un nom d'en-tête à un nom de variable d'environnement :

```toml
[mcp_servers.shager]
url = "https://app.shager.ai/api/mcp"
env_http_headers = { "Authorization" = "SHAGER_AUTH_HEADER" }
```

Sous cette forme, la variable doit contenir la valeur complète, schéma compris : `export SHAGER_AUTH_HEADER="Bearer shgr_live_..."`. Pour Shager, `bearer_token_env_var` est plus simple et fait la même chose.

## Comment limiter ce que Codex peut faire dans Shager ?

C'est l'étape que la plupart des guides d'installation passent sous silence. Codex permet de filtrer les outils d'un serveur avec `enabled_tools` (une liste d'autorisation) et `disabled_tools` (une liste d'exclusion appliquée ensuite), toutes deux documentées dans la référence de configuration. Combinez-les avec les scopes de clé de Shager et vous obtenez deux couches qui, en cas de doute, bloquent.

Un profil de rédaction qui peut tout lire et créer des brouillons, mais pas programmer, annuler ni créer de liens de connexion :

```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` reste dans la liste parce que, sans `schedule_at`, il ne fait qu'enregistrer un brouillon. Si la clé n'a pas non plus le scope `publish`, Shager rejette avec un 403 tout `create_post` qui contient `schedule_at` : même un modèle inventif ne peut pas glisser une publication programmée en douce.

La hausse de `tool_timeout_sec` s'explique par `upload_media_from_url`, qui télécharge le fichier côté serveur : une grosse vidéo verticale peut dépasser les 60 secondes par défaut indiquées dans la référence.

## Une première tâche qui vaut le coup

Commencez par un prompt qui sollicite plusieurs outils et ne laisse qu'un brouillon derrière lui :

```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.
```

Ce que vous devez obtenir : une publication au statut `DRAFT` avec une destination par compte, chacune avec son format résolu pour le réseau concerné. Dans Shager, chaque compte reçoit son propre lien court et ses tags UTM pour le `cta_url`, avec `utm_content` au nom du compte : c'est ce qui rend possible l'attribution par compte par la suite. Les détails sont dans [l'attribution des prospects par compte](/fr/blog/utm-per-account-lead-attribution).

## Codex peut-il tourner sans personne au clavier ?

Codex propose un mode non interactif, `codex exec`, pour les scripts et la CI. Le comportement des validations d'outils MCP en exécution headless a changé d'une version à l'autre : testez donc à blanc sur votre version installée avant de programmer quoi que ce soit. Pour une tâche qui doit tourner sans surveillance chaque semaine, beaucoup d'équipes se passent de la couche chat et appellent l'API REST de Shager depuis un petit script, sans invite de validation susceptible de bloquer. Quel que soit votre choix, donnez à la tâche sa propre clé, gardez une liste d'outils serrée, et décidez en connaissance de cause si cette clé porte `publish`. Une routine construite sur ces choix est détaillée dans [la routine de diffusion hebdomadaire](/fr/blog/skill-weekly-distribution-routine).

## Dépannage

| Ce que vous voyez | Cause | Solution |
|---|---|---|
| 401 `unauthorized` | Variable non exportée dans le shell qui a lancé Codex | `echo $SHAGER_API_KEY` dans le même terminal, puis redémarrez Codex |
| Outils absents de `/mcp` | Nom absent de `enabled_tools`, ou présent dans `disabled_tools` | Vérifiez l'orthographe avec la liste d'outils sur [/fr/agents](/fr/agents) |
| 403 `sandbox_unclaimed` | Clé issue de l'auto-inscription d'un agent, pas encore revendiquée par un humain | Envoyez le `claim_url` à une personne |
| 403 `forbidden` à la programmation | La clé n'a pas `publish` | Normal pour une clé de rédaction |
| 429 `rate_limited` | Plus de 120 requêtes par minute et par clé | Utilisez des groupes et un seul `create_post` au lieu d'un appel par compte |

## FAQ

### Codex a-t-il besoin d'OAuth pour communiquer avec Shager ?

Non. Codex prend en charge les jetons bearer lus dans une variable d'environnement, et Shager accepte une clé API de cette façon. Le serveur MCP de Shager prend aussi en charge la connexion OAuth, et Codex gère les serveurs OAuth : vous pouvez donc vous connecter plutôt que de gérer une clé.

### La configuration de Shager est-elle différente dans l'extension IDE de Codex ?

Selon la documentation MCP d'OpenAI, l'application de bureau ChatGPT, Codex CLI et l'extension IDE partagent cette configuration : la même table dans `~/.codex/config.toml` sert pour les trois. Assurez-vous que la variable d'environnement est visible par le processus de l'éditeur, ce qui, sur macOS, peut impliquer de lancer l'éditeur depuis un terminal.

### Puis-je brancher Codex sur l'API REST plutôt que sur MCP ?

Oui, si vous écrivez du code plutôt que de discuter. Le [document OpenAPI](https://app.shager.ai/api/v1/openapi.json) décrit les mêmes opérations que les outils MCP, avec les mêmes scopes et les mêmes limites.

## Et ensuite ?

Une fois Codex connecté, familiarisez-vous avec les opérations elles-mêmes avant d'automatiser quoi que ce soit. Le [guide de démarrage de l'API REST](/fr/blog/shager-rest-api-quickstart) parcourt toute la séquence, de l'espace de travail à la publication suivie, avec curl et Python, ce qui vous aide aussi à comprendre ce que fait Codex quand il appelle les outils MCP.

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