# Shager no OpenAI Codex: config.toml, bearer_token_env_var e uma lista de ferramentas que mantém rascunho como rascunho

_2026-08-20 · 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](https://developers.openai.com/codex/mcp), 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](https://developers.openai.com/codex/config-reference) 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:

```toml
[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:

```bash
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](https://github.com/openai/codex/blob/main/codex-rs/cli/src/mcp_cmd.rs)):

```bash
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:

```bash
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:

```toml
[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:

```toml
[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:

```text
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](/en/blog/utm-per-account-lead-attribution).

## 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](/en/blog/skill-weekly-distribution-routine).

## 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](/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](https://app.shager.ai/api/v1/openapi.json) 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](/en/blog/shager-rest-api-quickstart) 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.

---
Source: https://shager.ai/pt/blog/connect-shager-to-codex