# Shager in OpenAI Codex: config.toml, bearer_token_env_var und eine Tool-Allowlist, damit Entwürfe Entwürfe bleiben

_2026-08-20 · Richte den MCP-Server von Shager in der Codex CLI per config.toml oder codex mcp add ein, lies den Schlüssel aus einer Umgebungsvariable und begrenze die Tools._

Um Shager mit der Codex CLI von OpenAI zu verbinden, ergänzt du in `~/.codex/config.toml` eine Tabelle `[mcp_servers.shager]` mit `url = "https://app.shager.ai/api/mcp"` und `bearer_token_env_var = "SHAGER_API_KEY"` und exportierst deinen `shgr_live_`-Schlüssel in genau dieser Variable. Codex spricht Streamable HTTP von Haus aus und schickt den Schlüssel als Bearer-Token mit. Eine Bridge oder einen lokalen Prozess brauchst du also nicht. Alternativ geht es in einer Zeile mit `codex mcp add shager --url ... --bearer-token-env-var SHAGER_API_KEY`.

Im Rest dieser Anleitung geht es darum, das so aufzusetzen, dass du es später nicht bereust: den Schlüssel aus der Datei heraushalten, festlegen, welche Shager-Tools Codex aufrufen darf, und eine erste Aufgabe wählen, die beweist, dass die Verbindung steht.

## Was unterstützt Codex bei Remote-MCP-Servern?

Die [MCP-Dokumentation von Codex](https://developers.openai.com/codex/mcp) beschreibt Streamable-HTTP-Server, die über eine `url` konfiguriert werden, sowie drei Wege, sich per Header zu authentifizieren. Die [Konfigurationsreferenz](https://developers.openai.com/codex/config-reference) definiert sie so:

| Schlüssel | Was er macht |
|---|---|
| `bearer_token_env_var` | Name einer Umgebungsvariable, deren Wert als Bearer-Token gesendet wird |
| `http_headers` | Statische Header, die bei jeder Anfrage mitgeschickt werden |
| `env_http_headers` | Header, deren Werte aus Umgebungsvariablen gelesen werden |

Shager erwartet `Authorization: Bearer shgr_live_...`, und genau das erzeugt `bearer_token_env_var`. Das ist die Option der Wahl.

## Option A: config.toml bearbeiten

Öffne `~/.codex/config.toml` und füge hinzu:

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

Den Schlüssel selbst legst du in deinem Shell-Profil ab, nicht in der TOML-Datei:

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

Die Konfiguration enthält also nur den Namen der Variable, nicht den Schlüssel. Du kannst das Snippet deshalb bedenkenlos committen oder teilen, und jede Person im Team setzt ihren eigenen Schlüssel ein. Getrennte Schlüssel pro Person zahlen sich später aus, weil das Audit-Log von Shager unter https://app.shager.ai/dashboard/agents jeden Aufruf dem Schlüssel zuordnet, der ihn ausgelöst hat.

## Option B: codex mcp add

Die CLI schreibt dieselbe Tabelle für dich. Der Codex-Quellcode für `codex mcp add` definiert `--url` für Streamable-HTTP-Server und ein Flag `--bearer-token-env-var`, das `--url` voraussetzt ([mcp_cmd.rs auf 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
```

Weicht deine installierte Version davon ab, ist `codex mcp add --help` maßgeblich.

Prüf das Ergebnis:

```bash
codex mcp list
```

In der Codex-TUI zeigt `/mcp` die aktiven Server und ihre Tools.

## Solltest du stattdessen http_headers nehmen?

Du kannst, solltest es aber nicht. `http_headers = { "Authorization" = "Bearer shgr_live_..." }` funktioniert, legt aber ein gültiges Zugangsdatum in eine Klartextdatei, die gern mal in Dotfile-Repos kopiert wird. Brauchst du einen anderen Header als das Bearer-Token, ordnet `env_http_headers` einem Header-Namen den Namen einer Umgebungsvariable zu:

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

In dieser Form muss die Variable den vollständigen Wert samt Schema enthalten: `export SHAGER_AUTH_HEADER="Bearer shgr_live_..."`. Für Shager ist `bearer_token_env_var` einfacher und bewirkt dasselbe.

## Wie begrenzt du, was Codex in Shager tun darf?

Diesen Teil lassen die meisten Setup-Anleitungen weg. Codex kann die Tools eines Servers mit `enabled_tools` (eine Allowlist) und `disabled_tools` (eine Denylist, die danach greift) filtern. Beides steht in der Konfigurationsreferenz. Kombiniert mit den Scopes der Shager-Schlüssel ergeben sich zwei Ebenen, die im Zweifel blockieren.

Ein Profil fürs Entwerfen, das alles lesen und Entwürfe anlegen, aber weder planen noch stornieren noch Verbindungslinks erstellen kann:

```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` bleibt in der Liste, weil es ohne `schedule_at` nur einen Entwurf speichert. Fehlt dem Schlüssel zusätzlich der Scope `publish`, lehnt Shager jedes `create_post` mit `schedule_at` mit einem 403 ab. Selbst ein besonders einfallsreiches Modell kann also keinen geplanten Beitrag durchschmuggeln.

Der höhere Wert für `tool_timeout_sec` hat seinen Grund: `upload_media_from_url` lädt die Datei serverseitig herunter, und ein großes Hochformatvideo kann länger dauern als die 60 Sekunden, die die Referenz als Standard nennt.

## Eine erste Aufgabe, die sich lohnt

Starte mit einem Prompt, der mehrere Tools berührt und am Ende nur einen Entwurf hinterlässt:

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

Das solltest du sehen: einen Beitrag im Status `DRAFT` mit einem Ziel pro Konto, jeweils mit dem für dieses Netzwerk ermittelten Format. Shager gibt jedem Konto für die `cta_url` einen eigenen Kurzlink und eigene UTM-Tags, wobei `utm_content` das Konto benennt. Genau das macht die spätere Zuordnung pro Konto möglich. Die Details stehen in [Lead-Zuordnung pro Konto](/en/blog/utm-per-account-lead-attribution).

## Kann Codex das ohne Menschen an der Tastatur ausführen?

Codex hat mit `codex exec` einen nicht interaktiven Modus für Skripte und CI. Wie sich Freigaben für MCP-Tools in einem Headless-Lauf verhalten, hat sich zwischen den Releases geändert. Teste deshalb erst einen Probelauf mit deiner installierten Version, bevor du das Ganze zeitgesteuert laufen lässt. Für einen Job, der jede Woche unbeaufsichtigt laufen muss, verzichten viele Teams ganz auf die Chat-Ebene und rufen die REST-API von Shager aus einem kurzen Skript auf. Da gibt es keine Freigabeabfragen, an denen etwas hängen bleiben kann. Egal, wofür du dich entscheidest: Gib dem Job einen eigenen Schlüssel, halte die Tool-Allowlist eng und entscheide bewusst, ob dieser Schlüssel `publish` bekommt. Eine Routine, die auf diesen Entscheidungen aufbaut, beschreibt [die wöchentliche Distributionsroutine](/en/blog/skill-weekly-distribution-routine).

## Fehlersuche

| Was du siehst | Ursache | Lösung |
|---|---|---|
| 401 `unauthorized` | Variable ist in der Shell, aus der Codex gestartet wurde, nicht exportiert | `echo $SHAGER_API_KEY` im selben Terminal, dann Codex neu starten |
| Tools fehlen in `/mcp` | Name steht nicht in `enabled_tools` oder steht in `disabled_tools` | Schreibweise mit der Tool-Liste auf [/en/agents](/en/agents) abgleichen |
| 403 `sandbox_unclaimed` | Schlüssel stammt aus der Selbstregistrierung eines Agenten und wurde noch von keinem Menschen übernommen | Die `claim_url` an einen Menschen schicken |
| 403 `forbidden` beim Planen | Dem Schlüssel fehlt `publish` | Bei einem Schlüssel fürs Entwerfen so gewollt |
| 429 `rate_limited` | Mehr als 120 Anfragen pro Minute pro Schlüssel | Gruppen und ein einziges `create_post` nutzen statt eines Aufrufs pro Konto |

## FAQ

### Braucht Codex OAuth, um mit Shager zu sprechen?

Nein. Codex unterstützt Bearer-Tokens aus einer Umgebungsvariable, und Shager akzeptiert einen API-Schlüssel auf diesem Weg. Der MCP-Server von Shager unterstützt außerdem die Anmeldung per OAuth, und Codex kann ebenfalls mit OAuth-Servern umgehen. Wenn du keinen Schlüssel verwalten willst, kannst du dich also auch einfach anmelden.

### Ist das Setup in der IDE-Erweiterung von Codex anders?

Laut der MCP-Dokumentation von OpenAI teilen sich die ChatGPT-Desktop-App, die Codex CLI und die IDE-Erweiterung diese Konfiguration. Dieselbe Tabelle in `~/.codex/config.toml` gilt also für alle. Stell sicher, dass die Umgebungsvariable für den Editor-Prozess sichtbar ist. Unter macOS kann das heißen, den Editor aus einem Terminal heraus zu starten.

### Kann ich Codex statt auf MCP auf die REST-API ansetzen?

Ja, wenn du Code schreibst, statt zu chatten. Das [OpenAPI-Dokument](https://app.shager.ai/api/v1/openapi.json) beschreibt dieselben Operationen wie die MCP-Tools, mit denselben Scopes und Limits.

## Nächster Schritt

Sobald Codex verbunden ist, mach dich mit den Operationen selbst vertraut, bevor du irgendetwas automatisierst. Der [REST-API-Quickstart](/en/blog/shager-rest-api-quickstart) geht die komplette Abfolge vom Workspace bis zum getrackten Beitrag mit curl und Python durch. Das hilft dir auch, nachzuvollziehen, was Codex tut, wenn es die MCP-Tools aufruft.

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