Ponte pessoal entre um cliente MCP (incluindo ChatGPT) e o Codex CLI em um computador residencial. O computador só inicia conexões HTTPS de saída. As tarefas retornam um ID; status e resultados são consultados depois, sem prometer notificações espontâneas.

flowchart LR
    ChatGPT -->|HTTPS /mcp + OAuth| Cloud[Servidor FastAPI + SDK MCP]
    Cloud --> DB[(SQLite persistente)]
    Worker[Worker residencial] -->|HTTPS polling + token separado| Cloud
    Worker --> Journal[(Journal / outbox local)]
    Worker -->|stdio JSON RPC| Codex[Codex App Server dedicado]
    Codex --> Demo[Workspace local autorizado]
    Owner[Proprietário no PC] -->|aprovações locais| Journal
    IdP[Provedor OAuth estabelecido] -->|JWT RS256 + JWKS| Cloud

Início rápido local

Requer Python 3.12 e Codex CLI autenticado. Protocolo validado com Codex 0.162.1. Não altera Codex, Node, autenticação ou configurações globais. Node não é dependência do código Python; o SDK oficial MCP 2.3.0 está fixado no lockfile.

python3 -m venv .venv
.venv/bin/pip install uv==0.8.22
.venv/bin/uv sync --locked
.venv/bin/python examples/local_env.py
set -a
source private/local.env
set +a
.venv/bin/codex-bridge server

Em outro terminal, na mesma pasta:

set -a
source private/local.env
set +a
.venv/bin/codex-bridge worker

Em um terceiro terminal:

set -a
source private/local.env
set +a
.venv/bin/python examples/smoke_real.py

O smoke usa um cliente MCP real, chama o Codex real, retoma a thread em um novo processo App Server e verifica um arquivo inofensivo em demo/. Isto não comprova uma chamada originada no ChatGPT. O modelo do exemplo é gpt-6-luna; configure um modelo disponível na sua instalação se necessário. model/list confirma disponibilidade sem inferência. Se a sandbox da sessão hospedeira bloquear o processo Codex, execute o worker no seu terminal normal mantendo a sandbox própria do Codex e as aprovações.

Ferramentas

Ferramenta	Efeito
`bridge_status`	Disponibilidade, workspaces públicos, versão e contagem da fila
`submit_task`	Submissão rápida idempotente; pode alterar arquivos localmente
`get_task`	Estado, histórico, resultado, erro e IDs Codex
`get_task_events`	Eventos limitados e paginação incremental
`continue_task`	Novo turno na mesma thread; rejeita continuação concorrente
`cancel_task`	Solicita interrupção; não desfaz alterações
`list_tasks`	Listagem paginada e filtro por estado

Submissões recebem instruction, workspace, idempotency_key e opcionalmente timeout_seconds. O workspace é um identificador previamente autorizado; caminhos arbitrários e uma ferramenta genérica de shell não são expostos.

Produção

Configure .env a partir de .env.example, mantendo segredos fora do Git.
Configure um provedor OAuth estabelecido com PKCE S256, proprietário e audiência.
Inspecione o proxy existente e preencha rede, entrada TLS e certificate resolver.
Aponte o DNS público à VM e confirme certificados e HTTPS.
Execute docker compose --env-file .env up -d --build --wait --wait-timeout 90.
Configure o worker com URL HTTPS e token separado, usando apenas a demo inicialmente.
Cadastre /mcp no ChatGPT com OAuth e teste a partir do ChatGPT.

A configuração de produção falha se os dados OAuth estiverem ausentes. Não há porta publicada pelo Compose; Traefik acessa o container pela rede interna existente. A aplicação ignora todos os headers encaminhados; metadata e audiência vêm da URL configurada, e Host/Origin são verificados. A confiança nesses headers é, portanto, vazia.

Documentação

Testes

.venv/bin/pytest -q
.venv/bin/ruff check src tests examples
.venv/bin/ruff format --check src tests examples

Um proprietário, um worker, uma tarefa ativa, SQLite local ao servidor e polling com jitter/backoff. Não há garantia de exactly-once. Reservas expiradas não iniciam uma segunda execução: ficam em reconciliação. Resultados finais podem ser reenviados.