GitHub MCP Setup

GitHub MCP is project-local for this repository. Do not add it to the rendered global Codex config under home/dot_codex/config.toml.tmpl.

Keep the server in the ignored project config at .codex/config.toml:

[mcp_servers.github]
enabled = true
required = false
url = "https://api.githubcopilot.com/mcp/"
bearer_token_env_var = "GITHUB_MCP_TOKEN"
startup_timeout_sec = 10
tool_timeout_sec = 120

[mcp_servers.github.http_headers]
"X-MCP-Toolsets" = "repos,issues,pull_requests,actions"
"X-MCP-Readonly" = "true"
"X-MCP-Lockdown" = "false"

The server is configured as read-only planning context with the repos, issues, pull_requests, and actions toolsets. Repo mutation still goes through gh and git so issue updates, commits, pushes, and PR operations stay auditable.

Token

Create a fine-grained GitHub Personal Access Token (PAT) and store it only in the local agents env file. GitHub recommends fine-grained tokens because they can be limited to one owner, selected repositories, and specific permissions:

1. Open https://github.com/settings/personal-access-tokens/new, or navigate from GitHub through profile picture -> Settings -> Developer settings -> Personal access tokens -> Fine-grained tokens -> Generate new token.

2. Set Token name to something explicit, for example Codex GitHub MCP read-only.

3. Set Expiration to a bounded lifetime. Use the shortest lifetime that is practical for this workstation, or the maximum allowed by the owner policy if the token is for an organization.

4. Set Resource owner to the user or organization that owns the repositories Codex should inspect.

5. Under Repository access, choose Only select repositories and select the repositories Codex should be able to read. Do not choose all repositories unless that is intentionally the working set for this machine.

6. Under Repository permissions, grant only:

   Permission	Access
   Metadata	Read-only
   Contents	Read-only
   Issues	Read-only
   Pull requests	Read-only
   Actions	Read-only

7. Leave Account permissions and Organization permissions at No access. If a specific org-owned read fails later, add the narrow read-only org permission that GitHub reports as missing rather than widening the token preemptively.

8. Click Generate token and copy the token immediately. GitHub shows it only once.

Do not grant write or admin access, Workflows, Secrets, Webhooks, package permissions, Copilot request permissions, or broad organization administration permissions for this read-only planner setup. Organization-owned repositories may require owner approval or SAML SSO authorization before the token can read private resources.

Store the token locally:

install -d -m 700 .codex
touch .codex/.env
chmod 600 .codex/.env

Edit .codex/.env and set:

GITHUB_MCP_TOKEN=github_pat_REPLACE_ME

Do not commit the token. ~/.local/bin/codex-env loads the shared ~/.config/agents/.env first and then the nearest project-local .codex/.env before launching Codex, so this repo's token can override or supply GITHUB_MCP_TOKEN only for this project. The project-local Codex config passes that token to the GitHub MCP server through the bearer_token_env_var setting.

Classic PAT fallback: avoid classic PATs unless fine-grained tokens cannot cover the selected owner or API. A classic token with no scopes can only read public information. For private repository access, classic PATs generally require the broad repo scope, which is not read-only; prefer a fine-grained token instead. Add read:org only when an org metadata read is required and a fine-grained token is not usable.

References:

• https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens
• https://docs.github.com/en/copilot/how-tos/provide-context/use-mcp-in-your-ide/configure-toolsets
• https://github.com/github/github-mcp-server/blob/main/docs/server-configuration.md

Check

Verify the rendered global Codex config does not include the project-local GitHub MCP server:

python3 scripts/validate-codex-config.py

Then launch Codex through the managed wrapper so the local env file is loaded:

codex-env mcp list

If the GitHub MCP server is unavailable, required = false keeps Codex usable. Use GitHub MCP as optional read-only context and continue using gh as the deterministic source of truth for issue and PR mutation.