Shager in OpenAI Codex: config.toml, bearer_token_env_var und eine Tool-Allowlist, damit Entwürfe Entwürfe bleiben
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 beschreibt Streamable-HTTP-Server, die über eine url konfiguriert werden, sowie drei Wege, sich per Header zu authentifizieren. Die Konfigurationsreferenz 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:
[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:
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):
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:
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:
[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:
[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:
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.
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.
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 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 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 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.
