# 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`](https://github.com/geelen/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](https://bun.sh/) 1.2 or newer
- Codex CLI
- A web browser for Upwork OAuth

Clone and install dependencies:

```sh
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:

```sh
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`:

```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

```sh
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

```sh
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

```text
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](https://github.com/openai/codex/issues/29002)
- [Spec-valid annotations rejected by Codex](https://github.com/openai/codex/issues/38979)
- [MCP server connects but tools are not listed](https://github.com/openai/codex/issues/17246)
- [Request for better MCP diagnostics](https://github.com/openai/codex/issues/24439)

## Development

```sh
bun install --frozen-lockfile
bun test
```

## License

[MIT](LICENSE)