Codex ↔ Upwork MCP Bridge

An unofficial compatibility bridge for using Upwork's MCP server with OpenAI Codex and the ChatGPT desktop application.

The Upwork MCP server can authenticate and work in some MCP clients while Codex fails to expose its tools or reports an Unexpected response type error. This small stdio bridge runs mcp-remote, answers Upwork's server-to-client ping requests locally, and removes two cache hints observed on tools/list responses before forwarding them to Codex.

This is a community workaround, not an official Upwork or OpenAI project. Try Upwork's MCP endpoint directly first. The compatibility issue may be fixed upstream at any time.

Status

Tested on macOS with Codex CLI 0.149.0, Bun, and https://mcp.upwork.com/mcp. The same Codex MCP configuration is also available to the ChatGPT desktop application when both use the shared Codex configuration.

The exact failing field has not yet been isolated with a minimal upstream reproduction. The bridge normalizes both protocol differences observed during the failing exchange:

• It answers JSON-RPC ping requests sent from the server to the client.
• It removes ttlMs and cacheScope cache hints from tool-list results.

Those cache hints exist in newer MCP drafts; the interoperability concern is that they were returned while an older protocol revision was negotiated, not that the fields are universally invalid.

Install

Prerequisites:

• Bun 1.2 or newer
• Codex CLI
• A web browser for Upwork OAuth

Clone and install dependencies:

git clone https://github.com/drharunyuksel/codex-upwork-mcp-bridge.git
cd codex-upwork-mcp-bridge
bun install --frozen-lockfile

Register the bridge with Codex, replacing the example path with the absolute path to your clone:

codex mcp add upwork -- bun run /absolute/path/to/codex-upwork-mcp-bridge/src/index.ts

If you already have an MCP server named upwork, remove or rename that entry before running the command. Restart Codex and ChatGPT after changing MCP configuration. On first use, mcp-remote opens Upwork's OAuth authorization in your browser.

You can also add it manually to ~/.codex/config.toml:

[mcp_servers.upwork]
command = "/absolute/path/to/bun"
args = ["run", "/absolute/path/to/codex-upwork-mcp-bridge/src/index.ts"]
startup_timeout_sec = 60

Find Bun's absolute path with command -v bun.

Verify

codex mcp list
codex mcp get upwork

Then ask Codex to list the available Upwork tools or perform a read-only action, such as showing your Upwork profile. Avoid posting private tool output when reporting an issue.

Remove

codex mcp remove upwork

Removing the Codex entry does not remove mcp-remote's local OAuth session. Consult the mcp-remote documentation if you also want to clear that session.

How it works

Codex / ChatGPT  <-- stdio JSON-RPC -->  this bridge
                                             |
                                             v
                                        mcp-remote
                                             |
                                             v
                                 https://mcp.upwork.com/mcp

The bridge only changes the two observed compatibility points. Other JSON-RPC messages pass through. Protocol traffic stays on stdout; diagnostics go to stderr so they cannot corrupt the MCP stream.

Related Codex reports

This repository addresses the Upwork case, but similar reports describe Codex rejecting or failing to surface MCP tool results that work in other clients:

• Valid MCP results decoded as an unexpected response type
• Spec-valid annotations rejected by Codex
• MCP server connects but tools are not listed
• Request for better MCP diagnostics

Development

bun install --frozen-lockfile
bun test

License

MIT