Documentação do ChatGPT
Português
Contacto goolvyouyou@gmail.com

Model Context Protocol

Dê ao Codex acesso a ferramentas e contexto de terceiros

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 MCP servers e partilhar a respetiva configuração.

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

As funcionalidades de servidor suportadas abaixo aplicam-se aos MCP servers 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 MCP server 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 MCP server

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 MCP servers 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 MCP servers, pode alternar entre esses clientes sem repetir a configuração.

Configurar na aplicação ChatGPT para computador

  1. Abra Definições e, em seguida, selecione MCP servers.
  2. Selecione Adicionar servidor.
  3. Introduza um nome, escolha STDIO ou Streamable HTTP e forneça o comando ou URL do servidor.
  4. 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 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 MCP server 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 MCP servers 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 MCP server:

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 MCP server, 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 uma porta explícita, o Codex omite a porta de escuta no URL que apresenta e armazena e, em seguida, insere a porta de escuta ativa durante a autorização. Esta substituição não se aplica a localhost, a anfitriões IPv6, a URLs HTTPS nem a callbacks que já incluam uma porta. Os servidores de autorização têm de aceitar portas de loopback variáveis nos termos da RFC 8252, Secção 7.3.

Defina mcp_oauth_callback_port para escolher uma porta de escuta global fixa ou defina mcp_servers.<server-name>.oauth.callback_port para a substituir num servidor específico. Uma porta explícita no URL de callback não configura a escuta. Para um callback de loopback direto, utilize http://127.0.0.1 sem uma porta explícita ou configure a mesma porta explícita para o URL de callback e para a escuta. Um callback através de proxy pode utilizar intencionalmente uma porta de URL externa diferente da porta 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 MCP server 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 sem respostas vinculadas ao emissor, o Codex CLI utiliza um documento de metadados alojado no ChatGPT específico do MCP server:

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

O Codex deriva <callback_id> do URL do MCP server 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 Codex CLI também suporta um documento CIMD estável e partilhado:

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

O Codex CLI utiliza o documento estável com o caminho partilhado /callback quando o servidor de autorização anuncia authorization_response_iss_parameter_supported: true, fornece um valor válido de issuer nos seus metadados e inclui um valor correspondente de iss nas respostas de autorização. Os servidores sem respostas vinculadas ao emissor utilizam o documento específico do callback.

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

MCP servers fornecidos por plugins

Os plugins instalados podem incluir MCP servers 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 MCP servers 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 MCP servers fornecidos por plugins seguem as mesmas regras de seleção de callback que os restantes MCP servers. 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 MCP servers úteis

A lista de MCP servers 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).