Codex CLI

Codex supports streamable-HTTP MCP servers with bearer-token auth — full Pagelet tool access, no experimental flags.

Configure

Register a token first (one curl call) and put it in your environment:

export PAGELET_TOKEN=pgl_…   # add to ~/.zshrc, ~/.bashrc, …

Then declare the server in ~/.codex/config.toml:

# ~/.codex/config.toml
[mcp_servers.pagelet]
url = "https://pagelet.link/mcp"
bearer_token_env_var = "PAGELET_TOKEN"

bearer_token_env_var keeps the secret out of the file — Codex reads the variable and sends it asAuthorization: Bearer … on every MCP request. The same config is shared by the Codex CLI, the ChatGPT desktop app and the IDE extension, so this is a one-time setup. A project-scoped.codex/config.toml works too (trusted projects only).

Static or env-mapped headers also work if you prefer:

[mcp_servers.pagelet]
url = "https://pagelet.link/mcp"
http_headers = { "Authorization" = "Bearer pgl_…" }
# or pull values from the environment instead of literals:
env_http_headers = { "Authorization" = "PAGELET_AUTH_HEADER" }

Verify it works

• codex mcp list — pagelet appears as a configured server.
• In the TUI, /mcp shows active MCP servers for the session.
• Ask "call get_capabilities on pagelet" — it returns the live service manifest.

First pagelet

Ask: "Make a pagelet explaining this diff and publish it." Codex callspublish_pagelet and hands back a https://<slug>.usepagelet.com URL. Fetch it once to confirm it renders — that's success.

Troubleshooting

• "Auth required" tool errors — PAGELET_TOKEN isn't exported in the shell Codex runs from. Export it, restart Codex.
• Server doesn't start — remote servers initialize over the network; bump startup_timeout_sec (default 10) on slow connections.
• Empty tool list — check the URL is exactly https://pagelet.link/mcp, then /api/capabilities for service.mcp.
• Sandboxed runs can't publish — MCP calls go through Codex itself, but sandboxed shell commands have no network by default; don't ask Codex to curl the API as a fallback inside a sandbox.

Sources: Codex MCP guide andconfig reference (key names verified there).