MCP | Expandir o ChatGPT e o Codex | Documentação do ChatGPT

O Model Context Protocol (MCP) liga modelos a ferramentas e contexto. Utilize-o para dar ao ChatGPT ou ao Codex acesso a documentação de terceiros ou para permitir que interaja com ferramentas de desenvolvimento, como o seu navegador ou o Figma.

O ChatGPT na Web pode utilizar ferramentas remotas baseadas em MCP fornecidas por plugins. Depois de um plugin ser instalado, o Chat e o Work podem utilizar os conectores e as ferramentas MCP remotas nele incluídos. Abra o separador Plugins para procurar e gerir as ferramentas disponíveis. Os clientes Codex locais também podem estabelecer ligação diretamente a servidores MCP e partilhar a respetiva configuração.

A aplicação ChatGPT para computador, o Codex CLI e a extensão para IDE suportam servidores MCP e partilham a configuração de MCP para o mesmo anfitrião Codex.

As funcionalidades de servidor suportadas abaixo aplicam-se aos servidores MCP configurados num anfitrião Codex. As ferramentas de plugins alojadas podem ter capacidades diferentes.

Funcionalidades de MCP suportadas

Servidores STDIO: servidores executados como um processo local (iniciado por um comando).
- Variáveis de ambiente
Servidores HTTP com transmissão em fluxo: servidores aos quais acede através de um endereço.
- Autenticação por token Bearer
- Autenticação OAuth, incluindo Client ID Metadata Documents (CIMD) e Dynamic Client Registration (DCR)
- Autenticação de sessão do ChatGPT para servidores próprios fidedignos
Instruções do servidor: o Codex lê o campo MCP instructions devolvido durante a inicialização e utiliza-o como orientação para todo o servidor em conjunto com as ferramentas do servidor.

Se desenvolver ou mantiver um servidor MCP para o Codex, utilize instructions para fluxos de trabalho entre ferramentas, restrições e limites de taxa aplicáveis a todo o servidor. Mantenha os primeiros 512 caracteres autocontidos, para que as orientações mais importantes estejam disponíveis quando o Codex estiver a decidir como utilizar o servidor.

Ligar o Codex a um servidor MCP

O Codex armazena a configuração de MCP em config.toml, juntamente com outras definições de configuração do Codex. Por predefinição, trata-se de ~/.codex/config.toml, mas também pode limitar os servidores MCP a um projeto com .codex/config.toml (apenas projetos fidedignos).

A aplicação ChatGPT para computador, o Codex CLI e a extensão para IDE partilham esta configuração. Depois de configurar os seus servidores MCP, pode alternar entre esses clientes sem repetir a configuração.

Configurar na aplicação ChatGPT para computador

Abra Definições e, em seguida, selecione Servidores MCP.
Selecione Adicionar servidor.
Introduza um nome, escolha STDIO ou Streamable HTTP e forneça o comando ou URL do servidor.
Guarde o servidor e, em seguida, selecione Reiniciar.

A lista de servidores mostra quais estão ativados e quais requerem OAuth. Selecione Autenticar quando um servidor OAuth exigir início de sessão. No compositor, escreva /mcp para ver os servidores ligados.

Configurar com a 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 para documentação para programadores), pode executar 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 um servidor compatível com OAuth, execute codex mcp login <server-name>.

Interface de utilizador do terminal (TUI)

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

Configurar com config.toml

Para um controlo mais granular, edite ~/.codex/config.toml ou um ficheiro limitado ao projeto .codex/config.toml. Consulte a referência de configuração para obter uma lista pesquisável de todas as opções de MCP suportadas.

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

Servidores STDIO

command (obrigatório): o comando que inicia o servidor.
args (opcional): argumentos a transmitir ao servidor.
env (opcional): variáveis de ambiente a definir para o servidor.
env_vars (opcional): variáveis de ambiente a permitir e encaminhar.
cwd (opcional): diretório de trabalho a partir do qual iniciar o servidor.
experimental_environment (opcional): defina como remote para iniciar o servidor stdio através de um ambiente de execução remoto, quando estiver disponível.

env_vars pode conter nomes simples de variáveis ou objetos com uma origem:

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

As entradas de cadeia e source = "local" são lidas a partir do ambiente local do Codex. source = "remote" é lido a partir do ambiente de execução remoto e requer MCP stdio remoto.

Servidores Streamable HTTP

url (obrigatório): O endereço do servidor.
auth (opcional): Autenticação a tentar após os tokens bearer e os cabeçalhos de autorização configurados. Utilize oauth (a predefinição) para credenciais OAuth do MCP armazenadas. Utilize chatgpt para usar a sessão atual do ChatGPT para a origem fidedigna do ChatGPT, com OAuth armazenado como alternativa.
bearer_token_env_var (opcional): Nome da variável de ambiente de um token bearer a enviar em Authorization.
http_headers (opcional): Mapa de nomes de cabeçalhos para valores estáticos.
env_http_headers (opcional): Mapa de nomes de cabeçalhos para nomes de variáveis de ambiente (valores obtidos do ambiente).
http_headers_helper (opcional): Comando local que imprime um objeto JSON de nomes de cabeçalhos e valores de cadeia, como {"X-Auth": "temporary-token"}. Compatível com ligações HTTP MCP efetuadas a partir do ambiente local; não com servidores stdio nem com ligações efetuadas através de um ambiente de execução remoto.

O Codex coloca em cache os cabeçalhos auxiliares da ligação. Depois de um POST para a mesma origem devolver 401 ou 403, atualiza os cabeçalhos uma vez e só repete o pedido se o auxiliar devolver valores alterados. Os tokens bearer explícitos e as credenciais OAuth têm precedência sobre um cabeçalho Authorization fornecido pelo auxiliar. Uma resposta OAuth 403 que indique âmbito insuficiente não aciona uma atualização pelo auxiliar.

Se nenhuma origem de credenciais for resolvida, o Codex pode ligar-se ao servidor sem autenticação. Execute codex mcp login <server-name> separadamente para iniciar um início de sessão OAuth de MCP.

Outras opções de configuração

startup_timeout_sec (opcional): Tempo limite (segundos) para o servidor iniciar. Predefinição: 10.
tool_timeout_sec (opcional): Tempo limite (segundos) para o servidor executar uma ferramenta. Predefinição: 60.
enabled (opcional): Defina como false para desativar um servidor sem o eliminar.
required (opcional): Defina como true para fazer o arranque falhar se este servidor ativado não conseguir inicializar.
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 predefinido de aprovação para as ferramentas deste servidor. Os valores suportados são auto, prompt, writes e approve. O modo writes solicita aprovação para ferramentas que não estejam marcadas como só de leitura.
tools.<tool>.approval_mode (opcional): Substituição do comportamento de aprovação por ferramenta.
tools.<tool>.output_token_limit (opcional): Orçamento de tokens positivo para a saída de uma ferramenta, antes da margem padrão de serialização de 20%. Substitui o orçamento predefinido do modelo para truncar a saída dessa ferramenta.

A definição de nível superior mcp_optional_startup_grace_ms controla durante quanto tempo o Codex aguarda pelos servidores MCP opcionais ao criar o catálogo inicial de ferramentas. O valor predefinido é 1000 milissegundos. Defina-a como 0 para aguardar pelo startup_timeout_sec de cada servidor. Os servidores obrigatórios continuam a utilizar os respetivos tempos limite de arranque.

Registo do cliente OAuth e callbacks

Quando o seu servidor de autorização exigir um cliente OAuth previamente registado, forneça o respetivo ID de cliente ao adicionar o servidor MCP:

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

O Codex apresenta o URL de callback completo que deve registar junto do seu fornecedor:

OAuth callback URL: http://127.0.0.1/callback

O Codex guarda o callback juntamente com o ID de cliente em config.toml para inícios de sessão posteriores:

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

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

Os clientes previamente registados adicionados recentemente utilizam um callback estável apenas quando o servidor de autorização anuncia authorization_response_iss_parameter_supported: true e fornece um issuer nos metadados. Se o suporte do emissor não for anunciado, o Codex acrescenta um ID de callback específico do servidor, como http://127.0.0.1/callback/XuuuHAzzHOni. Os clientes existentes sem um callback guardado continuam a utilizar o redirecionamento específico do respetivo ID de callback.

Durante o início de sessão, a seleção do callback depende da configuração OAuth e dos metadados do servidor de autorização:

Configuração OAuth	Suporte do emissor	Callback utilizado
`callback_url` sem `client_id`	Suportado	O callback configurado é utilizado para o registo do cliente.
`callback_url` sem `client_id`	Não suportado	O callback configurado é utilizado para o registo do cliente, com o ID de callback específico do servidor acrescentado.
`client_id` e `callback_url`	Suportado	O callback configurado é reutilizado; a resposta de autorização tem de conter o `iss` correspondente.
`client_id` e um `callback_url` que termina no ID de callback correto	Não suportado	O callback configurado é reutilizado sem alterações.
`client_id` e um `callback_url` sem o ID de callback correto	Não suportado	O callback configurado é ignorado. O Codex utiliza `mcp_oauth_callback_url` ou, caso não esteja definido, `http://127.0.0.1/callback`, com o ID de callback acrescentado.
`client_id` sem um `callback_url` configurado	Suportado ou não suportado	O Codex utiliza o callback global ou predefinido, com o ID de callback específico do servidor acrescentado.

O mecanismo de contingência não modifica o URL de callback guardado. O Codex deriva o ID de callback do URL do servidor MCP, incluindo o respetivo caminho e cadeia de consulta. Aplicam-se as mesmas regras de seleção ao início de sessão automático e explícito.

Defina mcp_oauth_callback_url quando precisar de um caminho de callback personalizado ou de um URL de entrada remota do Devbox. Os clientes previamente registados adicionados recentemente utilizam esse URL sem alterações quando o respetivo fornecedor suporta a identificação do emissor. Caso contrário, utilizam o URL configurado com o ID de callback específico do servidor acrescentado. Registe sempre o callback exato apresentado por codex mcp add.

Para callbacks http://127.0.0.1 sem porta, o Codex omite a porta do serviço de escuta do URL que apresenta e guarda e, em seguida, insere a porta ativa do serviço de escuta durante a autorização. Esta substituição não se aplica a localhost, anfitriões IPv6, URLs HTTPS nem callbacks que já incluam uma porta. Os servidores de autorização têm de aceitar portas de loopback variáveis, em conformidade com a Secção 7.3 do RFC 8252.

Defina mcp_oauth_callback_port para escolher uma porta global fixa para o serviço de escuta ou defina mcp_servers.<server-name>.oauth.callback_port para a substituir num servidor. Uma porta explícita no URL de callback não configura o serviço de escuta. Para um callback de loopback direto, utilize http://127.0.0.1 sem porta ou configure a mesma porta explícita tanto para o URL de callback como para o serviço de escuta. Um callback através de proxy pode utilizar intencionalmente uma porta de URL externa diferente da porta do serviço de escuta local. Os URLs de callback locais vinculam-se à interface local; os URLs de callback não locais vinculam-se a 0.0.0.0.

O Codex valida qualquer iss devolvido antes de trocar o código de autorização. Um iss que não corresponda rejeita sempre a resposta. Quando o suporte do emissor é anunciado, a ausência de iss também provoca a rejeição. Nenhuma destas falhas troca o código nem recorre a outro callback. Um URL de callback malformado ou o anúncio de suporte do emissor sem um emissor nos metadados também continua a ser uma falha irrecuperável. Consulte Autenticar utilizadores.

Se o servidor MCP anunciar scopes_supported, o Codex dá preferência a esses âmbitos anunciados pelo servidor durante o início de sessão OAuth. Caso contrário, o Codex recorre aos âmbitos configurados em config.toml.

Registo do cliente OAuth

O Codex suporta OAuth Client ID Metadata Documents (CIMD) e Dynamic Client Registration (DCR). Por predefinição, o Codex escolhe automaticamente CIMD quando o servidor de autorização anuncia client_id_metadata_document_supported: true, inclui none em token_endpoint_auth_methods_supported e a chamada de retorno utiliza um URL de loopback suportado. Caso contrário, o Codex utiliza DCR quando disponível. Um ID de cliente OAuth configurado tem sempre precedência e ignora o registo do cliente.

Para CIMD, o Codex utiliza um documento de metadados alojado pelo ChatGPT específico do servidor MCP:

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

O Codex deriva <callback_id> do URL do servidor MCP e inclui-o no URI de redirecionamento de loopback, por exemplo, http://127.0.0.1:<port>/callback/<callback_id>. O documento de metadados regista o URI de loopback correspondente sem uma porta. Os servidores de autorização têm de aceitar a porta selecionada no início de sessão, fazendo corresponder exatamente o anfitrião e o caminho, conforme exigido pela RFC 8252. Anfitriões, caminhos ou parâmetros de consulta personalizados para a chamada de retorno requerem DCR ou um ID de cliente OAuth configurado.

O suporte para um documento CIMD estável e partilhado encontra-se em desenvolvimento e estará disponível em breve:

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

O Codex utilizará o documento estável com o caminho /callback partilhado quando o servidor de autorização anunciar authorization_response_iss_parameter_supported: true, fornecer um issuer válido nos respetivos metadados e incluir um iss correspondente nas respostas de autorização. Os servidores sem respostas vinculadas ao emissor continuarão a utilizar o documento específico da chamada de retorno.

Para escolher um método de registo para um início de sessão na CLI, utilize --oauth-client-registration:

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

A predefinição é auto. As opções de registo aplicam-se apenas ao início de sessão atual e não são armazenadas 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

Os plugins instalados podem incluir servidores MCP no respetivo manifesto. Esses servidores são iniciados a partir do plugin, pelo que a configuração do utilizador não define o respetivo comando de transporte. A configuração do utilizador continua a poder controlar o estado ativado/desativado e a política de 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"

Os servidores MCP HTTP fornecidos por plugins também podem declarar definições OAuth em .mcp.json. Os manifestos de plugins utilizam os nomes de campos em 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"
      }
    }
  }
}

Os servidores MCP fornecidos por plugins seguem as mesmas regras de seleção de callback que os restantes servidores MCP. Se um plugin fornecer um clientId, o respetivo fornecedor não suportar callbacks vinculados ao emissor e faltar a callbackUrl o ID de callback específico do servidor, o Codex ignora esse URL para o início de sessão e utiliza mcp_oauth_callback_url ou, caso não esteja definido, http://127.0.0.1/callback, com o ID de callback acrescentado. O callbackUrl configurado permanece inalterado.

O oauth.callbackPort de um plugin substitui o valor global de mcp_oauth_callback_port; se nenhum estiver definido, o Codex escolhe uma porta efémera. A porta incorporada em callbackUrl não seleciona a porta do serviço de escuta. Para um callback de loopback direto com uma porta fixa, configure ambos os valores de modo a coincidirem:

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

Para uma entrada remota ou outro proxy, a porta do URL de callback e a porta do serviço de escuta local podem ser intencionalmente diferentes quando o proxy reencaminha para o serviço de escuta configurado.

Exemplos de servidores MCP úteis

A lista de servidores MCP continua a crescer. Seguem-se alguns exemplos comuns:

OpenAI Docs MCP: pesquise e leia a documentação para programadores da OpenAI.
Context7: ligue-se a documentação atualizada para programadores.
Figma Local e Remoto: aceda aos seus designs do Figma.
Playwright: controle e inspecione um navegador com o Playwright.
Chrome Developer Tools: controle e inspecione o Chrome.
Sentry: aceda aos registos do Sentry.
GitHub: faça a gestão do GitHub para além do que git suporta (por exemplo, pull requests e problemas).

Pesquisas recentes

Pesquisas sugeridas

Navegação da documentação

Model Context Protocol