Skip to content

🤖 [codex] Add MCP config overlay support #92

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jonandersen merged 5 commits into from
May 8, 2026
Merged

🤖 [codex] Add MCP config overlay support #92

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
0c29551
Add Codex MCP config support
robmaceachern May 6, 2026
78c84e6
Match Codex MCP config overlay behavior
robmaceachern May 6, 2026
366dd72
Expand Codex MCP overlay test coverage
robmaceachern May 6, 2026
86f3be8
Propagate MCP generation errors
robmaceachern May 7, 2026
80c0128
Remove redundant Codex MCP docs note
robmaceachern May 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 60 additions & 0 deletions Cargo.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ clap = { version = "4.4", features = ["derive"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
serde_yaml = "0.9"
toml = "0.8"
cliclack = "0.3.6"
regex = "1.10"
which = "8.0.0"
Expand Down
13 changes: 12 additions & 1 deletion docs/agents.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
| **AMP** | `AGENTS.md` -> inlined file | `AGENTS.md` -> `ai-rules/AGENTS.md` | - | |
| **Claude Code** | `CLAUDE.md` -> inlined file | `CLAUDE.md` -> `ai-rules/AGENTS.md` | `.mcp.json` | |
| **Cline** | `.clinerules/AGENTS.md` -> inlined file | `.clinerules/AGENTS.md` -> `../ai-rules/AGENTS.md` | - | |
| **Codex** | `AGENTS.md` -> inlined file | `AGENTS.md` -> `ai-rules/AGENTS.md` | - | |
| **Codex** | `AGENTS.md` -> inlined file | `AGENTS.md` -> `ai-rules/AGENTS.md` | `.codex/config.toml` | Optional `ai-rules/codex-config.toml` overlay supported |
| **Copilot** | `AGENTS.md` -> inlined file | `AGENTS.md` -> `ai-rules/AGENTS.md` | - | |
| **Cursor** | `.cursor/rules/*.mdc` | `AGENTS.md` -> `ai-rules/AGENTS.md` | `.cursor/mcp.json` | Symlink mode: only project root level |
| **Firebender** | `AGENTS.md` -> inlined file | `AGENTS.md` -> `ai-rules/AGENTS.md` | `firebender.json` | Commands live in `.firebender/`; skills reuse `.agents/skills`; overlay supported |
Expand All @@ -26,3 +26,14 @@ Firebender supports overlay configuration files. To customize your configuration
`firebender.json` is generated as supplemental config when `ai-rules/mcp.json` and/or `ai-rules/firebender-overlay.json` exists.

**MCP Integration:** If you have `ai-rules/mcp.json`, the MCP servers are merged into `firebender.json` first, then the overlay is applied. This allows you to override MCP configurations in the overlay if needed.

## Codex Overlay Support

Codex supports overlay configuration files. To customize your configuration:

1. Create `ai-rules/codex-config.toml` in the same parent directory as your generated `.codex/config.toml`
2. Any values defined in the overlay file will be merged into the generated Codex configuration, with overlay values taking precedence

`.codex/config.toml` is generated when `ai-rules/mcp.json` and/or `ai-rules/codex-config.toml` exists.

**MCP Integration:** If you have `ai-rules/mcp.json`, the MCP servers are converted into Codex `[mcp_servers]` TOML first, then the overlay is applied. This allows you to override MCP configurations in the overlay if needed.
1 change: 1 addition & 0 deletions docs/mcp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ See the [Supported Agents](agents.md) table for which agents support MCP and the
| Agent | MCP File Location |
|-------|-------------------|
| Claude Code | `.mcp.json` |
| Codex | `.codex/config.toml` |
| Cursor | `.cursor/mcp.json` |
| Firebender | `firebender.json` (generated when MCP and/or overlay config exists) |
| Gemini | Embedded in `.gemini/settings.json` |
Expand Down
6 changes: 6 additions & 0 deletions docs/project-structure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ monorepo/
│ │ └── SKILL.md
│ ├── general.md # Repository-wide rules
│ ├── ai-rules-config.yaml # Configuration
│ ├── codex-config.toml # Codex config overlay (optional)
│ └── mcp.json # MCP server configuration
│
├── frontend/ # Frontend application
Expand Down Expand Up @@ -44,6 +45,8 @@ monorepo/
│ ├── commands/ # Firebender commands (generated symlinks)
├── .agents/
│ └── skills/ # Shared AMP/Firebender skills (generated symlinks)
├── .codex/
│ └── config.toml # Codex config (generated when mcp.json or codex-config.toml exists)
├── .mcp.json # Root MCP config (generated)
└── firebender.json # Root Firebender supplemental config (generated when needed)
```
Expand All @@ -61,6 +64,7 @@ project/
│ ├── skills/ # User-defined skills (optional)
│ │ └── debugging/
│ │ └── SKILL.md
│ ├── codex-config.toml # Codex config overlay (optional)
│ └── mcp.json # MCP config (optional)
│
├── CLAUDE.md # Symlink -> ai-rules/AGENTS.md
Expand All @@ -70,6 +74,8 @@ project/
│ ├── commands/ # Firebender commands (generated symlinks)
├── .agents/
│ └── skills/ # Shared AMP/Firebender skills (generated symlinks)
├── .codex/
│ └── config.toml # Codex config (if mcp.json or codex-config.toml exists)
├── firebender.json # Supplemental Firebender config (if mcp.json or overlay exists)
├── .clinerules/
│ └── AGENTS.md # Symlink -> ../ai-rules/AGENTS.md
Expand Down
Loading
Loading