Add MCP to Codex CLI Workflows
This research library uses AI-assisted source research and drafting. Linked sources support product claims; analysis and proposed exercises are our interpretation. Unless an article documents a test and its results, do not read it as a hands-on review or an independently verified benchmark.
Keep OpenAI's Codex CLI MCP setup narrow at first: connect one read-only server, tell Codex what it may use it for, and require a local verification step before you trust the result. For an engineering team, Codex MCP is useful when the CLI needs nearby context such as GitHub issues, docs, package metadata, or internal notes without pasting that material into every prompt.
In Codex training, I treat this as a workflow design problem before a tooling problem. The server gives Codex access to another system. Your job is to make that access boring, scoped, and reviewable.
Start with the integration boundary
Do not make the first Codex CLI MCP server write-capable. Read-only access gives the agent enough context to plan a change, but keeps commits, tickets, comments, and releases under human control.
Write down what the server may read, what it must not read, and what output you expect Codex to produce. I usually put that rule in AGENTS.md, because the point is not to remember the rule in chat. The point is to make the repo carry the rule.
A normal GitHub issue-to-PR workflow is a good first example: Codex reads the issue, inspects the relevant files, proposes a patch, runs the repo checks, and leaves the final PR text for a developer to review. For more repo-shaped examples, the companion note on Codex CLI Workflows from GitHub is a useful next read after this setup.
Wire the first server in small steps
Use the current OpenAI docs for the exact Codex CLI configuration shape. The workflow below is the part I would keep stable across teams.
Prerequisites:
- Codex CLI is installed and authenticated.
- The repository has at least one reliable local check, such as a unit test command, typecheck, lint, or build.
- You have one MCP server command or endpoint ready, with credentials that can be restricted.
- The repo has an
AGENTS.md, or you are allowed to add one.
Step 1: name the boundary.
Decide what this server is for before adding it to Codex. A GitHub server might be allowed to read issues and PR metadata, but not post comments or merge branches.
Step 2: create a low-privilege credential.
Use a read-only token or the narrowest permission set your system supports. Avoid sharing a personal all-access token with a Codex agent, even for a trial.
Step 3: add the server to Codex CLI.
Configure the MCP server using the supported Codex CLI mechanism for your installed version. Give the server a plain name such as github-readonly or docs-readonly, because that name will appear in prompts, logs, and review notes.
Step 4: teach the repo when to use it.
Add a short AGENTS.md rule that says when Codex may call the server and what it must do with the result. This belongs to the Design step in our methodology: set the boundary before asking the agent to build.
Step 5: verify with a harmless task.
Ask Codex to inspect an existing issue or document reference, summarize the relevant repo files, and run a local check without changing external state. The setup works when Codex can use the MCP context, explain what it used, and finish with a passing check or a clear failure.
Put the repo rule where Codex will read it
AGENTS.md should not become a policy essay. Keep it short enough that a developer will maintain it after the first week.
For a Codex CLI workflow connected to GitHub, I would start with a rule like this in the repo root, then add narrower files later if subdirectories need different behavior:
# AGENTS.md
## MCP usage
Codex may use the `github-readonly` MCP server to read issue and pull request context for the current task.
Codex must not use MCP tools to write comments, edit issues, change labels, approve PRs, merge branches, or trigger releases.
When MCP context affects a code change, Codex should mention the issue or PR it used in the final summary.
## Verification
Before proposing a final answer, run the smallest relevant local check:
- unit tests for touched code when available
- typecheck when types changed
- lint when formatting or imports changed
If a check cannot run locally, say why and name the command that should be run by a developer or CI.
Nested AGENTS.md files are useful once the repo has clear local ownership. A web app, API service, and database package may need different test commands and different MCP rules.
Use MCP for context, not authority
MCP adds external context. It does not make that context correct.
A Codex MCP server can return stale docs, partial issue history, or data that conflicts with the code. Tell Codex to treat MCP output as input to inspect, not as an instruction to obey. The codebase, tests, and human review still decide whether the change is acceptable.
The main tradeoff is speed against blast radius. A write-capable server can close the loop faster, but it also lets a mistaken agent affect systems outside the repo. I would only add write actions after the read-only path is boring and the team has review logs they actually read.
Paste this integration checklist
Use this before adding a new server to a Codex team workflow.
# Codex CLI MCP integration checklist
## Server boundary
- [ ] Server name is plain and specific: ____________________
- [ ] Server purpose is written in one sentence: ____________________
- [ ] First setup is read-only unless the team explicitly approved writes.
- [ ] Credential uses the narrowest available permission set.
- [ ] Secrets are not committed to the repo.
## AGENTS.md rule
- [ ] The repo says when Codex may use this MCP server.
- [ ] The repo says what Codex must not do through this server.
- [ ] The repo says how Codex should report MCP context in its final summary.
- [ ] Local verification commands are listed near the rule.
## Review loop
- [ ] First task is harmless and does not change external state.
- [ ] Codex can explain which MCP context it used.
- [ ] Codex runs a relevant local check or explains why it cannot.
- [ ] A developer reviews the diff and the MCP-derived assumptions.
- [ ] Write permissions stay disabled until the read-only flow is routine.
Further reading
Make one safe connection next
Pick one low-risk repo from your CLI workflows, add a read-only MCP server, and paste the checklist into the setup PR. If you want to practise this with a team, our hands-on training can run the same exercise as a Codex workshop with your own repo rules and verification loop.