SideButton

OpenAI Codex MCP Server — Install SideButton in Codex CLI

OpenAI Codex is a terminal coding agent that reads MCP servers from a TOML config. SideButton plugs in as one — exposing browser automation, an agentic workflow engine, and installable knowledge packs to every Codex session. Five-minute setup.

Why Add SideButton to OpenAI Codex — Browser Tools + Agentic Workflows

Codex excels at local reasoning over code — it reads your repo, edits files, and runs shell commands. What it does not ship with is a browser. Many real engineering tasks live outside the editor: verifying a UI change in the deployed app, extracting issues from Jira, walking a LinkedIn outreach sequence, reading a Grafana dashboard. SideButton closes that gap by handing Codex a real Chrome browser over MCP.

The second gain is domain context. Installable knowledge packs teach Codex the selectors, data model, and common workflows of specific apps. Instead of prompting Codex to guess DOM structure, the pack tells it exactly which attribute holds the ticket ID and which workflow archives a thread.

Third, everything stays local. Prompts, tool results, browser snapshots — all processed on your machine. The only thing that leaves is whatever Codex itself sends to OpenAI, and you control that via Codex's own config.

Prerequisites

  • Node.js 20 or later — required by the SideButton runtime
  • OpenAI Codex CLI — install with npm install -g @openai/codex or follow the OpenAI Codex README
  • OpenAI API key set in OPENAI_API_KEY or your Codex profile
  • Google Chrome (optional) for browser-automation tools

1. Install SideButton

If you already installed SideButton for another client (for example, following the Claude Code guide), skip to step 2. Otherwise:

$ npm install -g sidebutton

One install serves every MCP client on your machine — Codex and Claude Code can share it.

2. Edit Codex Config — Add the MCP Server in TOML

Codex stores its configuration in ~/.codex/config.toml (on Windows: %USERPROFILE%\.codex\config.toml). The file uses TOML, not JSON — watch for syntax gotchas mentioned below. Add this block: 

[mcp_servers.sidebutton]
command = "sidebutton"
args = ["serve", "--stdio"]

TOML gotchas

  • No trailing commas — TOML rejects them
  • Arrays use square brackets: args = ["serve", "--stdio"]
  • Section keys are case-sensitive: mcp_servers (underscore, lowercase)
  • Strings must be double-quoted in this context

3. Verify the Codex MCP Integration

Launch Codex and check that SideButton registered:

$ codex

Inside the session, run:

> /mcp list

You should see sidebutton with its tools. Install a pack tailored to Codex's typical use — engineering workflows in Linear:

$ sidebutton install linear.app

Then in Codex, try:

"Use sidebutton to pull every Linear issue tagged in-progress from the Backend team, then draft a stand-up summary grouping them by assignee."

Claude Code vs Codex — which one for SideButton?

Both clients expose the same SideButton surface. The right pick depends on your workflow and model preference.

Dimension Claude Code OpenAI Codex
Config format JSON (.claude.json) TOML (config.toml)
Underlying model Anthropic Claude family OpenAI GPT family
MCP transport stdio (default), SSE stdio (default), SSE
Best for Long agentic sessions, browser-heavy work Short edit loops, local repo reasoning
Sharing SideButton install Yes — same binary Yes — same binary

Dedicated deep-dive coming at /media — subscribe to the feed for the Claude Code vs Codex comparison.

Troubleshooting

Codex fails to parse config.toml

Almost always a TOML syntax issue — trailing comma after the last arg, missing quotes, or wrong section name. Run codex --check-config (if available) or paste the file into a TOML linter. Check that the section name is [mcp_servers.sidebutton] with an underscore.

model_context_protocol_error in session

Codex saw the server but got an unexpected message. Typically the sidebutton binary is not on PATH for Codex's spawn environment. Use an absolute path in command: find it with which sidebutton (or where sidebutton on Windows) and paste the full path into the TOML.

stdio vs SSE transport — which should I pick?

stdio (default) is simplest: Codex spawns SideButton as a child process. SSE is for cases where you want the server to outlive Codex — for example, sharing with Claude Code or another client at the same time. Switch by passing args = ["serve", "--sse", "--port", "3030"] and pointing Codex at the URL instead.

Where are the logs?

Codex logs to ~/.codex/logs/ by default. SideButton's stderr is captured there when launched via stdio. For deeper inspection, add "--verbose" to the args array and rerun.

Frequently asked questions

Does OpenAI Codex support MCP?

Yes. Codex CLI reads MCP server definitions from ~/.codex/config.toml. Any server exposing the Model Context Protocol over stdio or SSE works, including SideButton.

Why TOML instead of JSON like Claude Code?

That is a Codex-side choice — the rest of Codex's config lives in TOML, so MCP entries stay in the same file. The SideButton server does not care which format the client uses to bootstrap it; only the wire protocol matters.

Can I share one SideButton install between Codex and Claude Code?

Yes. One sidebutton binary serves every MCP client. Point Codex at it with the TOML entry on this page, and Claude Code at it with the JSON entry on the Claude Code page — each client opens its own stdio session to the same server.

Does this work for Codex Cloud or only the local CLI?

This guide covers the local Codex CLI. Codex Cloud runs in OpenAI's infrastructure and does not load local MCP servers — the SideButton path targets local, developer-controlled Codex workflows.

Related