Connect Codex to Planwright

OpenAI Codex connects to Planwright over Streamable HTTP via a single CLI command. Run it once, Codex registers the server and your browser opens for GitHub login. Service tokens and JSON config are available for CI and headless agents.

Setup

Run one command (Streamable HTTP), or create a JSON config file for CI.

1Run the codex mcp add command below. Your browser opens for GitHub login on first use.
2On first tool call, Codex connects and the Planwright tools become available.

Configuration

# Streamable HTTP — recommended (one command, no config file)
codex mcp add planwright --url https://mcp.planwright.tools/mcp

# Service token for CI / headless (Streamable HTTP):
codex mcp add planwright \
  --url https://mcp.planwright.tools/mcp \
  --header "Authorization: Bearer $PLANWRIGHT_TOKEN"

# ─── JSON config (for CI or headless runs) ───
# Generate a token at planwright.tools → Settings → MCP Token
{
  "mcpServers": {
    "planwright": {
      "type": "http",
      "url": "https://mcp.planwright.tools/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}
# Run: codex --mcp-config planwright-mcp.json

Verify the connection

Once Codex starts, ask it to:
"List my scheduled Planwright objectives"

Codex should call planwright_set_repo and
planwright_list_objectives and return the results.

Troubleshooting

codex mcp add is not recognized

The mcp add subcommand was added in a recent Codex release. Upgrade to the latest version, or use the JSON config path with --mcp-config planwright-mcp.json.

Which transport should I use?

Use Streamable HTTP (codex mcp add, /mcp endpoint) — it's the only supported path. SSE (/sse) is deprecated and will be removed on 2026-10-01.

Codex ignores the MCP config

Make sure you're passing --mcp-config with the correct path to your JSON file. Verify the file has no JSON syntax errors (no trailing commas, no comments).

OAuth flow doesn't open a browser

If your Codex build doesn't yet support OAuth discovery, switch to the service-token config. Generate a token at Settings → MCP Token.

← Quick install (all agents)Sign in to Planwright →