Model Context Protocol

O aplicativo do ChatGPT para desktop, a CLI do Codex e a extensão para IDE são compatíveis com servidores MCP e compartilham a configuração de MCP quando usam o mesmo host do Codex.

Os recursos abaixo se aplicam aos servidores MCP configurados em um host do Codex. As ferramentas de plugins hospedados podem oferecer recursos diferentes.

Recursos de MCP compatíveis

• Servidores STDIO: são executados como processos locais, iniciados por um comando.
  • Variáveis de ambiente
• Servidores Streamable HTTP: são acessados por um endereço.
  • Autenticação com token bearer
  • Autenticação OAuth, incluindo documentos de metadados de ID do cliente (CIMD) e registro dinâmico de clientes (DCR)
  • Autenticação pela sessão do ChatGPT para servidores próprios confiáveis
• Instruções do servidor: o Codex lê o campo instructions que o servidor MCP retorna durante a inicialização e usa essas instruções como orientação geral ao trabalhar com as ferramentas do servidor.

Se você cria ou mantém um servidor MCP para o Codex, use instructions para descrever fluxos de trabalho que envolvem várias ferramentas, restrições e limites de taxa que se aplicam a todo o servidor. Escreva os primeiros 512 caracteres de modo que façam sentido por si só. Assim, o Codex terá acesso às orientações mais importantes ao decidir como usar o servidor.

Conectar o Codex a um servidor MCP

O Codex armazena a configuração de MCP em config.toml, junto com as demais configurações do Codex. O caminho padrão é ~/.codex/config.toml, mas você também pode configurar servidores MCP para um projeto específico em .codex/config.toml (apenas para projetos confiáveis).

O aplicativo do ChatGPT para desktop, a CLI do Codex e a extensão para IDE compartilham essa configuração. Depois de configurar os servidores MCP, você pode alternar entre esses clientes sem repetir a configuração.

Configurar no aplicativo do ChatGPT para desktop

1. Abra Configurações e selecione Servidores MCP.
2. Selecione Adicionar servidor.
3. Informe um nome, escolha STDIO ou Streamable HTTP e insira o comando ou a URL do servidor.
4. Salve o servidor e selecione Reiniciar.

A lista mostra quais servidores estão ativados e quais exigem OAuth. Selecione Autenticar quando um servidor OAuth exigir login. No editor, digite /mcp para ver os servidores conectados.

Usar ferramentas MCP no ChatGPT na Web

Retomar em outro dispositivo uma conversa que usa o acesso ao computador local com o Work na nuvem não instala plugins nem concede acesso a contas conectadas.

No acesso ao computador local com o Work na nuvem, o requisito empresarial mcp_servers definido em TOML nas configurações de segurança do agente se aplica aos executores locais. Os contêineres na nuvem continuam sujeitos às políticas do Work na nuvem. Os servidores MCP e os transportes locais podem não estar disponíveis na nuvem. Verifique a conectividade e a autenticação separadamente.

Ao usar hooks empresariais no acesso ao computador local com o Work na nuvem, observe o seguinte:

• Hooks empresariais. Quando habilitado para o espaço de trabalho, o acesso ao computador local com o Work na nuvem permite usar hooks MCP definidos por administradores. Eles são executados no coordenador da nuvem (orquestrador) para os eventos de ciclo de vida e de ferramentas compatíveis. A orquestração na nuvem não oferece suporte a hooks de comando nem a hooks de configurações locais ou de plugins, mesmo quando as ferramentas são executadas localmente.
• Auditoria. Antes de depender desses hooks, teste a conexão de callback, confirme quais eventos ela recebe e verifique como as falhas afetam a tarefa. Os hooks MCP não fornecem uma trilha de auditoria completa da API de Compliance.
• Limitações: A orquestração na nuvem não oferece suporte a hooks de comando nem a hooks de configurações locais ou de plugins, mesmo quando as ferramentas são executadas localmente. Esse recurso não oferece suporte a hooks para usuários de planos pessoais. Quando tanto a orquestração quanto a execução são locais, os hooks compatíveis existentes continuam funcionando nas conversas exclusivamente locais do modo Work e do Codex. Os administradores ainda podem configurar os hooks gerenciados compatíveis nas configurações de segurança do agente para esses fluxos de trabalho.

Consulte Hooks e a Referência de configuração para saber quais recursos são compatíveis.

Em uma conversa hospedada do ChatGPT Work, instale um plugin para usar os conectores e as ferramentas MCP remotas que ele inclui. Após a instalação, os modos Chat e Work podem usar essas ferramentas. Os administradores do espaço de trabalho podem controlar quais plugins e ferramentas ficam disponíveis.

O ChatGPT na Web não lê os arquivos de configuração locais do Codex nem disponibiliza o menu de comandos local do Codex. Abra a aba Plug-ins para explorar e gerenciar as ferramentas disponíveis.

Configurar pela CLI

Adicionar um servidor MCP

codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <stdio server-command>

Por exemplo, para adicionar o Context7 (um servidor MCP gratuito de documentação para desenvolvedores), execute o seguinte comando:

codex mcp add context7 -- npx -y @upstash/context7-mcp

Outros comandos da CLI

Execute codex mcp list para ver os servidores configurados. Para ver todos os comandos MCP disponíveis, execute codex mcp --help. Para fazer login em um servidor compatível com OAuth, execute codex mcp login <server-name>. Se estiver usando um terminal sem navegador local, execute codex mcp login <server-name> --no-browser. Abra a URL de autorização exibida no terminal em um navegador e faça login. Cole a URL de redirecionamento completa no terminal, mesmo que o navegador não consiga carregar a página de callback.

Interface de usuário do terminal (TUI)

Na TUI do codex, use /mcp para ver os servidores MCP ativos.

Configurar na extensão para IDE

1. Abra o menu da engrenagem e selecione Servidores MCP.
2. Selecione Adicionar servidor.
3. Informe um nome, escolha STDIO ou Streamable HTTP e insira o comando ou a URL do servidor.
4. Salve o servidor e selecione Reiniciar extensão.

A lista de servidores MCP mostra quais estão ativados e quais exigem OAuth. Selecione Autenticar quando um servidor OAuth exigir login.

Configurar pelo config.toml

Para controlar a configuração em mais detalhes, edite ~/.codex/config.toml ou o arquivo .codex/config.toml de um projeto. Na referência de configuração, você pode pesquisar todas as opções de MCP compatíveis.

Configure cada servidor MCP em uma tabela [mcp_servers.<server-name>] no arquivo de configuração.

Servidores STDIO

• command (obrigatório): comando que inicia o servidor.
• args (opcional): argumentos a passar para o servidor.
• env (opcional): variáveis de ambiente a definir para o servidor.
• env_vars (opcional): variáveis de ambiente cujo encaminhamento ao servidor você autoriza.
• cwd (opcional): diretório de trabalho a partir do qual o servidor será iniciado.

env_vars aceita nomes de variáveis ou objetos que especificam a origem:

env_vars = ["LOCAL_TOKEN", { name = "REMOTE_TOKEN", source = "remote" }]

Para entradas do tipo string e entradas com source = "local", o Codex lê os valores do ambiente local. Com source = "remote", lê os valores do ambiente do executor remoto, o que exige suporte a MCP com stdio remoto.

Servidores Streamable HTTP

• url (obrigatório): endereço do servidor.
• auth (opcional): método de autenticação a tentar depois dos tokens bearer e cabeçalhos de autorização configurados. Use oauth (padrão) para usar as credenciais OAuth do MCP armazenadas. Use chatgpt para usar a sessão atual do ChatGPT com a origem própria confiável do ChatGPT, recorrendo às credenciais OAuth armazenadas como alternativa.
• bearer_token_env_var (opcional): nome da variável de ambiente que contém o token bearer a enviar em Authorization.
• http_headers (opcional): mapeamento de nomes de cabeçalhos para valores estáticos.
• env_http_headers (opcional): mapeamento de nomes de cabeçalhos para nomes de variáveis de ambiente. Os valores são obtidos do ambiente.
• http_headers_helper (opcional): comando local que imprime um objeto JSON com nomes de cabeçalhos e valores do tipo string, como {"X-Auth": "temporary-token"}. Essa opção está disponível para conexões MCP via HTTP feitas a partir do ambiente local. Ela não se aplica a servidores stdio nem a conexões feitas por um ambiente de execução remoto.

O Codex mantém em cache os cabeçalhos que o comando auxiliar fornece para a conexão. Se um POST para a mesma origem retornar 401 ou 403, o Codex atualiza os cabeçalhos uma vez e repete a solicitação somente se o comando auxiliar retornar valores diferentes. Tokens bearer explícitos e credenciais OAuth têm prioridade sobre um cabeçalho Authorization fornecido pelo comando auxiliar. Uma resposta OAuth 403 que indique escopo insuficiente não aciona a atualização dos cabeçalhos pelo comando auxiliar.

Se nenhuma fonte fornecer credenciais, o Codex poderá se conectar ao servidor sem autenticação. Execute codex mcp login <server-name> separadamente para iniciar o login no servidor MCP com OAuth.

Outras opções de configuração

• environment_id seleciona o ambiente para um servidor stdio ou Streamable HTTP. O valor padrão é local. Para se conectar por meio de um executor remoto, use o ID de ambiente registrado desse executor.
• startup_timeout_sec (opcional): tempo limite, em segundos, para o servidor iniciar. Padrão: 10.
• tool_timeout_sec (opcional): tempo limite, em segundos, para o servidor executar uma ferramenta. Padrão: 60.
• enabled (opcional): defina como false para desativar um servidor sem excluí-lo.
• Defina required = true para que a inicialização do Codex falhe se esse servidor estiver ativado, mas ainda não estiver pronto. A configuração padrão, startup_readiness = "connection", exige uma conexão ativa. Defina startup_readiness = "catalog" para permitir que o Codex conclua a inicialização com um catálogo de ferramentas válido em cache enquanto o servidor se conecta. As chamadas de ferramentas continuam exigindo uma conexão ativa.
• enabled_tools (opcional): lista de ferramentas permitidas.
• disabled_tools (opcional): lista de ferramentas bloqueadas, aplicada após enabled_tools.
• default_tools_approval_mode (opcional): comportamento padrão de aprovação das ferramentas desse servidor. Os valores aceitos são auto, prompt, writes e approve. O modo writes pede aprovação para ferramentas que não estão marcadas como somente leitura.
• tools.<tool>.approval_mode (opcional): substitui o comportamento de aprovação para uma ferramenta específica.
• tools.<tool>.output_token_limit (opcional): número positivo que define o limite de tokens da saída de uma ferramenta antes do acréscimo padrão de 20% para serialização. Substitui o limite padrão que o modelo usa para truncar a saída dessa ferramenta.

A configuração de nível superior mcp_optional_startup_grace_ms controla por quanto tempo o Codex aguarda os servidores MCP opcionais ao montar o catálogo inicial de ferramentas. O padrão é 1000 milissegundos. Defina como 0 para usar o tempo de espera especificado em startup_timeout_sec de cada servidor. Os servidores obrigatórios continuam usando seus próprios tempos limite de inicialização.

Registro de clientes OAuth e callbacks

Se o servidor de autorização exigir um cliente OAuth previamente registrado, informe o ID do cliente ao adicionar o servidor MCP:

codex mcp add example --url https://mcp.example.com --oauth-client-id my-client

Para um cliente confidencial, passe também --oauth-client-secret. Leia o segredo de uma variável de ambiente:

codex mcp add example --url https://mcp.example.com --oauth-client-id my-client --oauth-client-secret "$MCP_CLIENT_SECRET"

Essa opção exige que tanto o ID do cliente quanto o segredo estejam preenchidos. O Codex salva o segredo em mcp_servers.example.oauth.client_secret no arquivo config.toml. Mantenha esse arquivo privado e fora do controle de versão.

Registre a URL de callback exatamente como aparece na saída de codex mcp add. Quando o servidor de autorização anuncia suporte à identificação do emissor, a CLI pode exibir a seguinte URL:

OAuth callback URL: http://127.0.0.1/callback

Para o cliente público deste exemplo, o Codex salva o callback e o ID do cliente em config.toml para os próximos logins:

[mcp_servers.example]
url = "https://mcp.example.com"

[mcp_servers.example.oauth]
client_id = "my-client"
callback_url = "http://127.0.0.1/callback"

Clientes previamente registrados que acabam de ser adicionados só usam um callback estável quando o servidor de autorização anuncia authorization_response_iss_parameter_supported: true e fornece um issuer nos metadados. Se o servidor não anunciar suporte à identificação do emissor, o Codex acrescenta à URL um ID de callback específico do servidor, como em http://127.0.0.1/callback/XuuuHAzzHOni. Clientes existentes sem um callback salvo continuam usando o redirecionamento específico do seu ID de callback.

Durante o login, a escolha do callback depende da configuração OAuth e dos metadados do servidor de autorização:

O uso de um callback alternativo não altera a URL de callback armazenada. O Codex deriva o ID de callback da URL do servidor MCP, incluindo o caminho e a string de consulta. As mesmas regras de seleção se aplicam ao login automático e ao explícito.

Defina mcp_oauth_callback_url se precisar de um caminho de callback personalizado ou de uma URL de entrada de um Devbox remoto. Clientes previamente registrados que acabam de ser adicionados usam essa URL sem alterações quando o provedor oferece suporte à identificação do emissor. Caso contrário, usam a URL configurada com o ID de callback específico do servidor ao final. Sempre registre o callback exatamente como aparece na saída de codex mcp add.

Para callbacks em http://127.0.0.1 sem porta explícita, o Codex omite a porta de escuta da URL que exibe e armazena. Durante a autorização, insere a porta de escuta ativa. Essa substituição não se aplica a localhost, hosts IPv6, URLs HTTPS nem a callbacks que já incluem uma porta. Os servidores de autorização devem aceitar portas de loopback variáveis conforme a seção 7.3 da RFC 8252.

Defina mcp_oauth_callback_port para escolher uma porta de escuta global fixa ou mcp_servers.<server-name>.oauth.callback_port para substituí-la em um servidor específico. Informar uma porta explícita na URL de callback não configura a porta de escuta. Para um callback direto por loopback, use http://127.0.0.1 sem porta explícita ou configure a mesma porta explícita na URL de callback e na escuta. Se o callback passar por um proxy, a porta da URL externa pode ser intencionalmente diferente da porta de escuta local. Para URLs de callback locais, o Codex escuta na interface local. Para URLs de callback não locais, escuta em 0.0.0.0.

O Codex valida qualquer iss retornado antes de trocar o código de autorização. Se o iss não corresponder ao emissor, o Codex sempre rejeitará a resposta. Quando o servidor anuncia suporte à identificação do emissor, a ausência de iss também leva à rejeição. Em ambos os casos, o Codex não troca o código nem tenta outro callback. Uma URL de callback malformada ou o anúncio de suporte à identificação do emissor sem um emissor nos metadados também impede o login. Consulte Autenticar usuários.

Defina mcp_servers.<server-name>.scopes em config.toml para escolher os escopos OAuth de um servidor. Para substituí-los em um único login, execute codex mcp login <name> --scopes read,write. Se nenhuma das duas opções estiver definida, o Codex solicita os escopos indicados no desafio inicial WWW-Authenticate do servidor. Se o desafio não especificar escopos, o Codex usa os escopos anunciados nos metadados do recurso protegido, quando disponíveis.

Uma lista vazia (scopes = []) ainda permite que a biblioteca OAuth escolha os escopos. A biblioteca também pode adicionar offline_access se o servidor de autorização oferecer suporte a esse escopo.

Registro de clientes OAuth

O Codex oferece suporte a documentos de metadados de ID do cliente OAuth (CIMD) e ao registro dinâmico de clientes (DCR). Por padrão, o Codex escolhe CIMD automaticamente quando o servidor de autorização anuncia client_id_metadata_document_supported: true, inclui none em token_endpoint_auth_methods_supported e o callback usa uma URL de loopback compatível. Caso contrário, o Codex usa DCR quando disponível. Um ID de cliente OAuth configurado sempre tem prioridade e dispensa o registro do cliente.

Para CIMD sem respostas vinculadas ao emissor, a CLI do Codex usa um documento de metadados específico do servidor MCP, hospedado no ChatGPT:

https://chatgpt.com/oauth/codex/<callback_id>/client.json

O Codex deriva <callback_id> da URL do servidor MCP e o inclui no URI de redirecionamento de loopback, como em http://127.0.0.1:<port>/callback/<callback_id>. O documento de metadados registra o URI de loopback correspondente sem a porta. Os servidores de autorização devem aceitar a porta escolhida durante o login e exigir correspondência exata do host e do caminho, conforme a RFC 8252. Hosts, caminhos ou parâmetros de consulta personalizados no callback exigem DCR ou um ID de cliente OAuth configurado.

A CLI do Codex também aceita um documento CIMD estável e compartilhado:

https://chatgpt.com/oauth/codex/client.json

A CLI do Codex usa o documento estável com o caminho compartilhado /callback quando o servidor de autorização anuncia authorization_response_iss_parameter_supported: true, fornece um issuer válido nos metadados e inclui um iss correspondente nas respostas de autorização. Servidores sem respostas vinculadas ao emissor usam o documento específico do callback.

Para escolher o método de registro em um único login pela CLI, use --oauth-client-registration:

codex mcp login <server-name> --oauth-client-registration cimd
codex mcp login <server-name> --oauth-client-registration dcr

O padrão é auto. A escolha do método de registro vale apenas para o login atual e não é salva em config.toml.

Exemplos de config.toml

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["LOCAL_TOKEN"]

[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"

# Optional MCP OAuth callback overrides (used by `codex mcp login`)
mcp_oauth_callback_port = 5555
mcp_oauth_callback_url = "https://devbox.example.internal/callback"

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"] # applied after enabled_tools
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45
enabled = true

[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"
output_token_limit = 30000

Servidores MCP fornecidos por plugins

Plugins instalados podem incluir servidores MCP em seus manifestos. O próprio plugin inicia esses servidores, por isso a configuração do usuário não define o comando de transporte deles. O usuário ainda pode ativá-los ou desativá-los e definir a política das ferramentas em plugins.<plugin>.mcp_servers.<server>.

[plugins."sample@test".mcp_servers.sample]
enabled = true
default_tools_approval_mode = "prompt"
enabled_tools = ["read", "search"]

[plugins."sample@test".mcp_servers.sample.tools.search]
approval_mode = "approve"

Servidores MCP via HTTP fornecidos por plugins também podem declarar configurações OAuth em .mcp.json. Nos manifestos de plugins, os nomes dos campos usam camelCase: clientId, callbackUrl e callbackPort.

{
  "mcpServers": {
    "sample": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "clientId": "my-pre-registered-client",
        "callbackUrl": "http://127.0.0.1/callback/registered"
      }
    }
  }
}

Servidores MCP fornecidos por plugins seguem as mesmas regras de seleção de callback que os demais servidores MCP. Se um plugin fornecer um clientId, o provedor não oferecer suporte a callbacks vinculados ao emissor e a callbackUrl não incluir o ID de callback específico do servidor, o Codex ignorará essa URL no login. Nesse caso, usará mcp_oauth_callback_url ou, se essa opção não estiver definida, http://127.0.0.1/callback, acrescentando o ID de callback à URL. A callbackUrl configurada permanece inalterada.

O valor de oauth.callbackPort do plugin tem prioridade sobre a configuração global mcp_oauth_callback_port. Se nenhum dos dois estiver definido, o Codex escolherá uma porta efêmera. A porta incluída em callbackUrl não define a porta de escuta. Para um callback direto por loopback com porta fixa, configure os dois valores com a mesma porta:

{
  "callbackUrl": "http://127.0.0.1:4321/callback/registered",
  "callbackPort": 4321
}

No caso de um ponto de entrada remoto ou de outro proxy, a porta da URL de callback pode ser intencionalmente diferente da porta de escuta local, desde que o proxy encaminhe as solicitações à porta de escuta configurada.

Exemplos de servidores MCP úteis

A lista de servidores MCP continua crescendo. Estes são alguns dos mais comuns:

• OpenAI Docs MCP: pesquise e leia a documentação da OpenAI para desenvolvedores.
• Context7: conecte-se a fontes atualizadas de documentação para desenvolvedores.
• Figma Local e Remoto: acesse seus designs do Figma.
• Playwright: controle e inspecione um navegador com o Playwright.
• Ferramentas do desenvolvedor do Chrome: controle e inspecione o Chrome.
• Sentry: acesse os logs do Sentry.
• GitHub: gerencie recursos do GitHub que vão além do que o git oferece, como pull requests e issues.