Shager no OpenAI Codex: config.toml, bearer_token_env_var e uma lista de ferramentas que mantém rascunho como rascunho
Configure o MCP remoto do Shager no Codex CLI via config.toml ou codex mcp add, leia a chave de uma variável, limite as ferramentas e crie um rascunho.
Para conectar o Shager ao Codex CLI da OpenAI, adicione uma tabela [mcp_servers.shager] ao ~/.codex/config.toml com url = "https://app.shager.ai/api/mcp" e bearer_token_env_var = "SHAGER_API_KEY" e depois exporte a sua chave shgr_live_ nessa variável. O Codex fala streamable HTTP de forma nativa e envia a chave como bearer token, então não é preciso nenhuma ponte nem processo local. Também dá para fazer tudo em uma linha com codex mcp add shager --url ... --bearer-token-env-var SHAGER_API_KEY.
O restante deste guia mostra como fazer isso de um jeito do qual você não vai se arrepender: mantendo a chave fora do arquivo, limitando quais ferramentas do Shager o Codex pode chamar e escolhendo uma primeira tarefa que prove que a ligação funciona.
O que o Codex oferece para servidores MCP remotos?
A documentação de MCP do Codex, da OpenAI, descreve servidores streamable HTTP configurados com uma url, além de três formas de autenticação por header. A referência de configuração define cada uma:
| Chave | O que faz |
|---|---|
bearer_token_env_var |
Nome de uma variável de ambiente cujo valor é enviado como bearer token |
http_headers |
Headers fixos incluídos em cada requisição |
env_http_headers |
Headers cujos valores são lidos de variáveis de ambiente |
O Shager espera Authorization: Bearer shgr_live_..., que é exatamente o que o bearer_token_env_var gera. É essa a opção a usar.
Opção A: editar o config.toml
Abra o ~/.codex/config.toml e adicione:
[mcp_servers.shager]
url = "https://app.shager.ai/api/mcp"
bearer_token_env_var = "SHAGER_API_KEY"
Depois, coloque a chave no perfil do seu shell, e não no TOML:
export SHAGER_API_KEY="shgr_live_your_key_here"
Repare que a configuração guarda o nome da variável, não a chave. Isso significa que você pode commitar ou compartilhar o trecho à vontade, e cada pessoa da equipe usa a própria chave. Ter uma chave por pessoa compensa mais tarde, porque o registro de auditoria do Shager em https://app.shager.ai/dashboard/agents grava cada chamada junto com a chave que a fez.
Opção B: codex mcp add
A CLI escreve a mesma tabela para você. O código-fonte do codex mcp add define --url para servidores streamable HTTP e uma flag --bearer-token-env-var que depende dela (mcp_cmd.rs no GitHub):
codex mcp add shager \
--url https://app.shager.ai/api/mcp \
--bearer-token-env-var SHAGER_API_KEY
Se a versão instalada for diferente, quem manda é o codex mcp add --help.
Confira o resultado:
codex mcp list
Dentro da TUI do Codex, /mcp mostra os servidores ativos e as ferramentas de cada um.
Vale usar http_headers no lugar?
Dá, mas não vale. http_headers = { "Authorization" = "Bearer shgr_live_..." } funciona e coloca uma credencial ativa num arquivo de texto puro, que costuma acabar copiado para repositórios de dotfiles. Se você precisar de um header que não seja o bearer token, o env_http_headers associa o nome de um header ao nome de uma variável de ambiente:
[mcp_servers.shager]
url = "https://app.shager.ai/api/mcp"
env_http_headers = { "Authorization" = "SHAGER_AUTH_HEADER" }
Nesse formato, a variável precisa conter o valor completo, incluindo o esquema: export SHAGER_AUTH_HEADER="Bearer shgr_live_...". No Shager, o bearer_token_env_var é mais simples e faz a mesma coisa.
Como limitar o que o Codex pode fazer no Shager?
Esta é a parte que a maioria dos guias de configuração pula. O Codex permite filtrar as ferramentas de um servidor com enabled_tools (uma lista de permissões) e disabled_tools (uma lista de bloqueio aplicada depois dela), ambas documentadas na referência de configuração. Combine isso com os escopos da chave do Shager e você terá duas camadas que, na dúvida, bloqueiam.
Um perfil de redação que lê tudo e cria rascunhos, mas não consegue agendar, cancelar nem criar links de conexão:
[mcp_servers.shager]
url = "https://app.shager.ai/api/mcp"
bearer_token_env_var = "SHAGER_API_KEY"
enabled_tools = [
"whoami",
"list_workspaces",
"list_channels",
"list_groups",
"upload_media_from_url",
"create_post",
"get_post",
"list_posts",
"get_analytics",
]
tool_timeout_sec = 120
O create_post continua na lista porque, sem schedule_at, ele só salva um rascunho. Se a chave também não tiver o escopo publish, o Shager rejeita com 403 qualquer create_post que inclua schedule_at; assim, nem um modelo criativo consegue passar um post agendado escondido.
O aumento do tool_timeout_sec existe porque o upload_media_from_url baixa o arquivo no servidor, e um vídeo vertical grande pode levar mais do que os 60 segundos padrão indicados na referência.
Uma primeira tarefa que vale rodar
Comece com um prompt que passe por várias ferramentas e deixe só um rascunho para trás:
Use o servidor MCP shager.
1. whoami e depois list_workspaces.
2. No espaço de trabalho "Lakeside Realty", list_channels e list_groups.
3. upload_media_from_url https://example.com/media/open-house.jpg
4. create_post como rascunho para o grupo "All agents" com uma legenda diferente
por canal (per_channel), citando o bairro de cada corretor a partir do nome
do canal. cta_url https://lakesiderealty.example/open-house, campaign
"open-house-oct", first_comment "Detalhes e confirmação: " seguido do link.
5. get_post e mostre uma tabela com canal, rede, formato e estado.
O que você deve ver: um post com status DRAFT e um destino por conta, cada um com o formato já resolvido para aquela rede. No Shager, cada conta ganha o próprio link curto e as próprias tags UTM para a cta_url, com o utm_content identificando a conta, e é isso que viabiliza a atribuição por conta mais adiante. Os detalhes estão em atribuição de leads por conta.
O Codex consegue rodar isso sem ninguém no teclado?
O Codex tem um modo não interativo, codex exec, para scripts e CI. O comportamento das aprovações de ferramentas MCP numa execução sem interface mudou entre versões, então faça um teste a seco na versão instalada antes de colocar isso num agendador. Para uma tarefa que precisa rodar sozinha toda semana, muitas equipes pulam a camada de chat e chamam a API REST do Shager a partir de um script curto, que não tem pedidos de aprovação em que possa travar. Seja qual for a escolha, dê à tarefa uma chave própria, mantenha a lista de ferramentas enxuta e decida conscientemente se essa chave terá publish. Uma rotina construída em cima dessas escolhas está descrita em a rotina semanal de distribuição.
Solução de problemas
| O que aparece | Causa | Solução |
|---|---|---|
401 unauthorized |
A variável não foi exportada no shell que abriu o Codex | Rode echo $SHAGER_API_KEY no mesmo terminal e reinicie o Codex |
Ferramentas faltando no /mcp |
O nome não está em enabled_tools ou está em disabled_tools |
Confira a grafia com a lista de ferramentas em /en/agents |
403 sandbox_unclaimed |
A chave veio do autocadastro do agente e nenhuma pessoa assumiu a conta | Envie o claim_url para uma pessoa |
403 forbidden ao agendar |
A chave não tem publish |
É o esperado numa chave de redação |
429 rate_limited |
Mais de 120 requisições por minuto por chave | Use grupos e um único create_post, em vez de uma chamada por conta |
Perguntas frequentes
O Codex precisa de OAuth para falar com o Shager?
Não. O Codex aceita bearer tokens vindos de uma variável de ambiente, e o Shager aceita uma chave de API desse jeito. O servidor MCP do Shager também aceita login via OAuth, e o Codex também aceita servidores com OAuth, então entrar com a sua conta é uma opção se você preferir não gerenciar uma chave.
A configuração do Shager muda na extensão do Codex para IDE?
A documentação de MCP da OpenAI diz que o app de desktop do ChatGPT, o Codex CLI e a extensão para IDE compartilham essa configuração, então a mesma tabela no ~/.codex/config.toml atende a todos. Garanta que a variável de ambiente esteja visível para o processo do editor; no macOS, isso pode significar abrir o editor a partir de um terminal.
Posso apontar o Codex para a API REST em vez do MCP?
Pode, se você estiver escrevendo código em vez de conversar. O documento OpenAPI descreve as mesmas operações das ferramentas MCP, com os mesmos escopos e limites.
Próximo passo
Com o Codex conectado, familiarize-se com as próprias operações antes de automatizar qualquer coisa. O guia rápido da API REST percorre toda a sequência, do espaço de trabalho ao post rastreado, com curl e Python, o que também ajuda a entender o que o Codex está fazendo quando chama as ferramentas MCP.
