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. Os clientes Codex locais também podem ligar-se 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 Streamable HTTP: servidores a que acede através de um endereço.
    • Autenticação por token Bearer
    • Autenticação OAuth
    • 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

  1. Abra Definições e, em seguida, selecione Servidores MCP.
  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 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 configurados e os cabeçalhos de autorização. Utilize oauth (a predefinição) para credenciais OAuth de MCP armazenadas. Utilize chatgpt para usar a sessão atual do ChatGPT para a origem ChatGPT própria fidedigna, recorrendo ao OAuth armazenado como alternativa.
  • bearer_token_env_var (opcional): nome da variável de ambiente para 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).

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 false para desativar um servidor sem o eliminar.
  • required (opcional): defina true para fazer com que o arranque falhe 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 de aprovação predefinido para 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.

Se o seu fornecedor de OAuth exigir uma porta de retorno de chamada fixa, defina mcp_oauth_callback_port no nível superior em config.toml. Se não estiver definido, o Codex associa-se a uma porta efémera.

Se o seu fluxo OAuth de MCP tiver de utilizar um URL de retorno de chamada específico (por exemplo, um URL de entrada de Devbox remoto ou um caminho de retorno de chamada personalizado), defina mcp_oauth_callback_url. O Codex utiliza este valor como URL de retorno de chamada base e, em seguida, acrescenta um ID de retorno de chamada específico do servidor para produzir o redirect_uri OAuth que envia durante o início de sessão. Registe o redirect_uri completo derivado junto do seu fornecedor de OAuth, incluindo o ID de retorno de chamada acrescentado e qualquer caminho, consulta ou porta configurados, em vez de registar apenas o anfitrião ou caminho base sem esse sufixo. Os URLs de retorno de chamada locais (por exemplo, localhost) associam-se à interface local; os URLs de retorno de chamada não locais associam-se a 0.0.0.0 para que o retorno de chamada possa alcançar o anfitrião.

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.

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"

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"

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).