> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vertracloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Use a Vertra Cloud no Codex (CLI, extensão de IDE e app)

> Conecte o Codex à Vertra Cloud via MCP: entre com sua conta ou use uma chave de API, faça deploy da sua pasta, aprovações e primeiros prompts.

O Codex acessa a Vertra Cloud pelo servidor MCP oficial. A CLI do Codex, a extensão de IDE e o app do Codex leem o
mesmo `~/.codex/config.toml`, então você configura uma vez só. Veja [MCP](https://docs.vertracloud.app/pt-br/mcp.md) para saber o que o servidor pode e não pode fazer.

## Qual servidor devo adicionar?

* **Servidor remoto**: você entra com sua conta Vertra no navegador e nenhuma chave vai para um arquivo. Fazer deploy a partir de uma
  pasta não está disponível. Escolha-o para investigar, operar e configurar.
* **Servidor local**: todas as ferramentas, incluindo `create_app` e `deploy_app`, que compactam e enviam a pasta do projeto. Ele
  usa uma chave de API. Escolha-o se for fazer deploy pelo Codex.

## Adicione o servidor remoto

**1. Adicione à configuração**

Em `~/.codex/config.toml`:

```toml ~/.codex/config.toml theme={null}
[mcp_servers.vertracloud]
url = "https://mcp.vertracloud.app/mcp"
```

**2. Entre**

```bash theme={null}
codex mcp login vertracloud
```

O navegador abre a tela de consentimento da Vertra, que mostra o destino como **App no seu computador**. Marque os
escopos que quer conceder e confirme. Em uma máquina sem navegador, adicione `--no-browser` e abra o link que ele
imprime.

**3. Confira a conexão**

Execute `codex mcp list` no terminal, ou `/mcp` dentro do Codex. Na extensão de IDE, a lista de servidores MCP mostra o servidor como
ativado.

O login cria uma chave de API com o prefixo `oauth:` em **Configurações → Chaves de API**; revogue-a lá para desconectar.

### Servidor remoto com uma chave de API

Se preferir não entrar pelo navegador, envie uma chave de API no header. Exporte a chave no seu shell e aponte o
Codex para a variável:

```toml ~/.codex/config.toml theme={null}
[mcp_servers.vertracloud]
url = "https://mcp.vertracloud.app/mcp"
bearer_token_env_var = "VERTRA_API_KEY"
```

## Adicione o servidor local

**1. Crie uma chave de API**

No dashboard, vá em **Configurações → Chaves de API**, crie uma chave com os escopos de que precisa e copie. Para fazer deploy, marque
`apps:read`, `apps:write` e `apps:files`. Para só investigar, `apps:read` basta.

**2. Exporte a chave no seu shell**

Adicione ao perfil do seu shell (`~/.zshrc`, `~/.bashrc`) e abra um novo terminal:

```bash theme={null}
export VERTRA_API_KEY="your_key"
```

**3. Adicione o servidor**

`env_vars` repassa a variável do seu shell para o servidor, então a chave não vai para o arquivo.
`startup_timeout_sec` dá ao `npx` tempo para baixar o pacote na primeira execução (o padrão é 10 segundos):

```toml ~/.codex/config.toml theme={null}
[mcp_servers.vertracloud]
command = "npx"
args = ["-y", "@vertracloud/mcp"]
env_vars = ["VERTRA_API_KEY"]
startup_timeout_sec = 30
```

**4. Confira a conexão**

Inicie o Codex na pasta do projeto e execute `/mcp`. O servidor só mexe em arquivos dentro da pasta em que foi
iniciado; veja [Os arquivos locais ficam na pasta do projeto](https://docs.vertracloud.app/pt-br/mcp.md#os-arquivos-locais-ficam-na-pasta-do-projeto).

`codex mcp add vertracloud --env VERTRA_API_KEY=your_key -- npx -y @vertracloud/mcp` faz o mesmo pelo terminal,
mas grava a chave em texto puro no `config.toml`.

Para manter o servidor em um único projeto, coloque o mesmo bloco em `.codex/config.toml` na raiz do projeto. O Codex lê esse arquivo
em projetos que você marcou como confiáveis.

## Pergunte antes de toda alteração

Toda ferramenta da Vertra informa ao cliente se ela só lê. Com `writes`, o Codex executa as leituras sozinho e pergunta antes de
qualquer coisa que altere sua conta, como fazer deploy, reiniciar, excluir ou definir uma variável:

```toml ~/.codex/config.toml theme={null}
[mcp_servers.vertracloud]
url = "https://mcp.vertracloud.app/mcp"
default_tools_approval_mode = "writes"
```

## Conte ao Codex sobre o seu projeto

Adicione algumas linhas ao `AGENTS.md` do projeto para que o Codex saiba a quais recursos da Vertra o código pertence:

```markdown AGENTS.md theme={null}
## Deploy (Vertra Cloud)
- Este repositório é a aplicação `orders-api` da Vertra Cloud; o banco de dados dela é `orders-db` (PostgreSQL).
- Faça o deploy com o servidor MCP `vertracloud` (`deploy_app` nesta pasta, com uma mensagem) e depois `wait_for_app`.
- Antes de reiniciar, fazer rollback ou alterar variáveis, mostre os logs e me pergunte.
```

## Primeiros prompts

* "Liste meus apps na Vertra e diga quais estão down."
* "Por que o `orders-api` caiu? Leia as últimas 300 linhas de log antes de mudar qualquer coisa."
* "Faça deploy desta pasta no `orders-api` com a mensagem 'fix checkout timeout' e espere até ficar online."

Mais em [Fluxos do dia a dia](https://docs.vertracloud.app/pt-br/mcp/workflows.md).

## Solução de problemas

| O que aparece | O que fazer |
| - | - |
| O servidor não aparece em `/mcp` | Confira `codex mcp list`; o Codex só lê o `.codex/config.toml` do projeto em projetos confiáveis |
| O servidor local expira ao iniciar | Aumente `startup_timeout_sec` e confira se `node -v` é 18 ou mais novo |
| `NOT_AUTHENTICATED` no servidor local | `VERTRA_API_KEY` não está exportada no terminal que iniciou o Codex, ou está faltando em `env_vars` |
| `NOT_AUTHENTICATED` no app do Codex ou na extensão da IDE | Um app aberto fora do terminal pode não enxergar as variáveis do perfil do shell: abra-o pelo terminal ou use o servidor remoto |
| `NOT_AUTHENTICATED` no servidor remoto | Execute `codex mcp login vertracloud` de novo |
| `create_app` e `deploy_app` não aparecem | Você está no servidor remoto; adicione o local |
| `API_KEY_SCOPE_DENIED` | Crie uma chave com o escopo da ferramenta, ou entre de novo marcando-o |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.