codex-mcp-proxy

Use a remote MCP server that you have already authenticated in Codex from Claude Code, without going through the server's OAuth flow a second time.

Some MCP servers only allow OAuth clients that the vendor has registered (Codex, ChatGPT, and so on), so Claude Code's own login fails or is blocked by an admin policy. This tool sidesteps that: Claude Code launches codex-mcp-proxy as a plain stdio MCP server, and the proxy forwards every JSON-RPC message to the remote server using the OAuth tokens Codex stored when you logged in there.

Claude Code  --stdio-->  codex-mcp-proxy  --HTTPS + Bearer <Codex token>-->  remote MCP server

How it works

• Server definition comes from Codex's ~/.codex/config.toml ([mcp_servers.<name>] with a url).

• Tokens come from where Codex keeps them: the macOS Keychain item with service Codex MCP Credentials and account <name>|<sha256 prefix>, or the file fallback ~/.codex/.credentials.json. The hash input is undocumented, so the proxy enumerates the keychain items by the <name>| prefix when its guess misses, and add bakes the resolved account into the Claude Code registration so later launches go straight to it.

• Transport is Streamable HTTP, with automatic fallback to the older SSE transport when the server answers the first POST with 404/405.

• Refresh: when the access token is about to expire the proxy refreshes it with the stored refresh token and client id, then writes the new tokens back into Codex's store so both tools stay in sync (disable with --no-write-back).

• No interactive login: if refresh fails, the proxy reports a clear error telling you to log in again in Codex.

The proxy is transparent: initialize, tools, prompts, resources, notifications, and server-initiated requests all pass through unchanged.

Related MCP server: ccg-mcp

Requirements

• Node.js 20+

• Codex installed, with the MCP server already logged in there (run codex, then /mcp)

• macOS for keychain access; on other platforms Codex uses the credentials file, which is also supported

Install

cd mcp-proxy
npm install
npm run build
npm link          # puts `codex-mcp-proxy` on your PATH

Usage

# 1. See which Codex MCP servers can be proxied
codex-mcp-proxy list

# 2. Verify credentials are found and the server answers
codex-mcp-proxy check glean_default

# 3. Register it with Claude Code (runs `claude mcp add` for you)
codex-mcp-proxy add glean_default --name glean --scope user

Then restart Claude Code (or run /mcp) and the server's tools appear under the name you chose.

The first time the proxy reads a Codex keychain item, macOS shows a keychain prompt. Choose Always Allow so Claude Code can start the proxy without prompting again. A separate prompt appears for each server's item.

Commands

Options

Manual registration

If you prefer to edit config yourself, the equivalent of add is:

claude mcp add --transport stdio --scope user glean -- codex-mcp-proxy glean_default

Troubleshooting

• "No Codex OAuth credentials found": log in to the server in Codex first with codex mcp login <server> (or /mcp inside Codex). Run codex-mcp-proxy key <server> to see which keychain accounts are checked; --account overrides the derivation.

• "could not be refreshed": the refresh token was rejected, so Codex's own session is dead too. Run codex mcp login <server>; the proxy picks up the new tokens on its next start. Confirm with codex-mcp-proxy check <server>.

• Keychain prompt every time: choose Always Allow in the macOS prompt, or the proxy has to ask on each launch.

• Server-side 4xx after connecting: run check <server> -v to see the HTTP status and transport used; --transport sse forces the legacy transport.

Development

npm run build                      # compile to dist/
node scripts/smoke.mjs glean_default   # drive the proxy over stdio like an MCP client