tmcproxy

Minimal MCP stdio compatibility proxy that bridges OpenAI Secure MCP Tunnel / ChatGPT connectors to legacy stdio MCP servers.

The problem this solves

ChatGPT connectors (via OpenAI Secure MCP Tunnel) probe stdio MCP servers with server/discover — a method introduced in MCP 2026-07-28. Legacy servers like codex mcp-server and local-mcp mcp only speak 2025-06-18 and return method not found for server/discover, causing connector creation to fail.

tmcproxy sits in between, answers server/discover on the downstream's behalf, and forwards every other request verbatim.

ChatGPT → tunnel-client → tmcproxy → codex mcp-server (or local-mcp mcp)
                                ↑
                   answers server/discover here,
                   forwards everything else straight through

Requirements

• Node.js >= 23.6.0 (for native TypeScript strip-mode execution — no build step needed)

Usage

Standalone

node src/tmcproxy.ts -- codex mcp-server
node src/tmcproxy.ts -- local-mcp mcp

Or via environment variable:

TMCPROXY_DOWNSTREAM="codex mcp-server" node src/tmcproxy.ts

With tunnel-client

Edit your tunnel-client profile YAML (e.g. ~/.config/tunnel-client/<profile>.yaml):

mcp:
  commands:
    - channel: main
      command: "node /path/to/tmcproxy/src/tmcproxy.ts -- codex mcp-server"

Then:

tunnel-client run --profile <profile>

Switching downstreams is just changing the command after --:

      command: "node /path/to/tmcproxy/src/tmcproxy.ts -- local-mcp mcp"

How it works

Request	Behavior
server/discover	Proxy answers with a spec-shaped DiscoverResult. Capabilities are probed from the downstream via tools/list (not guessed).
initialize	Forwarded verbatim to downstream. The proxy never calls initialize itself — codex mcp-server allows it exactly once, so the client's handshake must be the one that reaches it.
tools/list, tools/call, ping, etc.	Forwarded verbatim with JSON-RPC id preserved.
Notifications (no id)	Forwarded; no response expected.
Malformed JSON	-32700 Parse error returned to upstream, not forwarded.
Unknown method	Forwarded; downstream error flows back.

Why supportedVersions includes 2026-07-28

ChatGPT probes with 2026-07-28. If the response only lists 2025-06-18, ChatGPT treats it as "requested version not supported" and retries indefinitely — never reaching initialize or tools/list. By listing 2026-07-28, ChatGPT enters modern mode and sends stateless requests (tools/list, tools/call) directly. The legacy downstream answers these without a prior initialize (confirmed for both codex mcp-server and local-mcp mcp), so transparent forwarding works.

Debugging

Debug log

Set TMCPROXY_DEBUG=1 to log server/discover requests and responses to stderr:

TMCPROXY_DEBUG=1 tunnel-client run --profile local-codex

Output on stderr (stdout stays clean — it's the MCP channel):

[tmcproxy] downstream: ["codex","mcp-server"]
[tmcproxy] discover request: {"jsonrpc":"2.0","id":"openai-mcp-discover",...}
[tmcproxy] discover response: {"resultType":"complete","supportedVersions":["2026-07-28","2025-06-18"],...}

Local end-to-end test (no API key needed)

tunnel-client dev proxy runs a local in-memory control plane that reproduces the same MCP probe flow ChatGPT uses:

tunnel-client dev proxy \
  --mcp-command "command=node /path/to/tmcproxy/src/tmcproxy.ts -- codex mcp-server,channel=main" \
  --url-file /tmp/url.json \
  --duration 30s

MCP_URL=$(node -e "console.log(JSON.parse(require('fs').readFileSync('/tmp/url.json','utf8')).mcp_url)")
curl -sS -X POST "$MCP_URL" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: server/discover' \
  -d '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28"}}}'

Baseline comparison

To confirm the proxy is needed, run the downstream directly through dev proxy and observe the server/discover failure:

tunnel-client dev proxy \
  --mcp-command "command=codex mcp-server,channel=main" \
  --url-file /tmp/url.json --duration 30s
# server/discover → -32601 method not found

Tests

pnpm install
pnpm test          # unit + integration
pnpm test:unit     # mock downstream only
pnpm test:integration  # real codex / local-mcp (auto-skipped if not installed)
pnpm typecheck

Unit tests use a mock downstream (test/fixtures/mock-downstream.js) and cover: discover response shape, capability probing, initialize forwarding, tools/list, tools/call id preservation, ping, unknown methods, malformed JSON, notifications, stderr mirroring, downstream exit handling, and stdout leak detection.

Integration tests spawn the real codex mcp-server and local-mcp mcp binaries if available on PATH.

Security

• Diagnostics go to stderr only; stdout is reserved for MCP traffic.
• No credentials, API keys, or secrets are logged.
• Downstream is spawned via argv (no shell).
• Only server/discover is handled by the proxy; all other requests pass through unchanged.
• The proxy does not expand the downstream's permissions.

License

Apache-2.0