# Servidor MCP — a API da Oveyon como ferramentas do seu agente | Oveyon

> Ligue o Claude Code, o Claude Desktop, o Cursor, o VS Code, o Codex CLI ou o Windsurf à Oveyon pelo MCP: uma ferramenta por rota da API, só as que os escopos da chave liberam, e cada envio retido para uma pessoa aprovar, se você quiser. Incluído em todos os planos.

Versão em texto de https://oveyon.com.br/mcp.
In English: https://oveyon.com/mcp
Se você é um agente e precisa de e-mail, o procedimento está em https://oveyon.com.br/llms.txt

Servidor MCP

## A API inteira, _como ferramentas_ do seu agente.

MCP — Model Context Protocol — é o padrão aberto com que os clientes de IA chamam ferramentas de fora: o agente pergunta ao servidor que ferramentas ele tem e chama cada uma pelo nome. O nosso transforma cada rota da API da Oveyon numa ferramenta, dentro dos escopos, dos limites e do registro da sua chave.

[Criar conta grátis](https://app.oveyon.com/app)
[Documentação](https://api.oveyon.com/?lang=pt)

Incluído em todos os planos, inclusive no gratuito · Claude Code, Claude Desktop, Cursor, VS Code, Codex CLI, Windsurf

**Claude Code** terminal

```
# 1. conecte, com a chave do agente
claude mcp add --transport http oveyon https://mcp.oveyon.com/v1 --header "Authorization: Bearer ov_SUA_CHAVE"

# 2. peça, em português
> De quais domínios eu posso enviar?
→ list_domains
```

O servidor

### Um endereço, e a chave que você já tem.

Sem conta nova, sem senha nova: o servidor atende pela chave de API da conta, pelo mesmo portão da API REST.

- **Endereço**: `https://mcp.oveyon.com/v1` — o endereço antigo, `https://api.oveyon.com/v1/mcp`, também funciona e continua funcionando
- **Transporte**: Streamable HTTP, sem estado: só POST
- **Autenticação**: `Authorization: Bearer ov_SUA_CHAVE` — a chave de API da conta; 401, 403 e 429 idênticos aos da API REST
- **Ferramentas**: Uma por rota da API REST — 76 —, e o servidor lista só as que os escopos da chave liberam; `whoami` e `check_disposable` valem em toda chave
- **whoami**: A conta, a chave e quais ferramentas estão ou não disponíveis, com o escopo que cada uma exige
- **Guia**: O resource `oveyon://guide` traz o procedimento para o agente
- **Mesmas regras**: Toda chamada de ferramenta é uma chamada à API com a mesma chave: escopos, cotas, políticas, idempotência e o registro de chamadas valem sem mudança — no Registro de chamadas, elas aparecem com a família `oveyon-mcp`
- **Erros**: Chegam inteiros ao modelo: o código do erro, a mensagem e o `Retry-After`
- **Preço**: Incluído em todos os planos, inclusive no gratuito; o que o agente envia conta na cota do plano, como sempre

Quatro passos

### Conectado em quatro passos.

#### 1. Escolha o cliente

Claude Code, Claude Desktop, Cursor, VS Code, Codex CLI ou Windsurf — ou qualquer cliente que mande um cabeçalho. Cada um guarda a configuração num lugar diferente.

#### 2. Crie uma chave para o agente

Pela tela do MCP no painel (Envio → MCP): os escopos sugeridos já vêm marcados, e também «Exigir aprovação humana para os envios desta chave». A chave aparece uma única vez.

#### 3. Cole a configuração

Envio → MCP a imprime para o seu cliente, e ela também está abaixo. Troque `ov_SUA_CHAVE` pela chave — no cliente, nunca num repositório.

#### 4. Peça ao agente

Em palavras simples. Ele escolhe e chama as ferramentas; com a trava ligada, o que ele envia espera uma pessoa em Mensagens → Aprovações.

Configuração

### Cole isto no seu cliente.

O mesmo texto que o painel imprime em Envio → MCP. Troque `ov_SUA_CHAVE` pela chave do agente.

#### Claude Code

No terminal:

**terminal**

```
claude mcp add --transport http oveyon https://mcp.oveyon.com/v1 --header "Authorization: Bearer ov_SUA_CHAVE"
```

#### Claude Desktop

Em Configurações → Desenvolvedor → Editar configuração. A ponte mcp-remote manda o cabeçalho pelo Claude Desktop.

**claude_desktop_config.json**

```
{
  "mcpServers": {
    "oveyon": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@0.14.3",
        "https://mcp.oveyon.com/v1",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${OVEYON_AUTH}"
      ],
      "env": {
        "OVEYON_AUTH": "Bearer ov_SUA_CHAVE"
      }
    }
  }
}
```

#### Cursor

Em `~/.cursor/mcp.json` — não no `.cursor/mcp.json` do projeto, que costuma ir para o repositório.

**~/.cursor/mcp.json**

```
{
  "mcpServers": {
    "oveyon": {
      "url": "https://mcp.oveyon.com/v1",
      "headers": {
        "Authorization": "Bearer ov_SUA_CHAVE"
      }
    }
  }
}
```

#### VS Code

Em `.vscode/mcp.json`. O VS Code pede a chave uma vez e a guarda como segredo — ela não fica no arquivo.

**.vscode/mcp.json**

```
{
  "servers": {
    "oveyon": {
      "type": "http",
      "url": "https://mcp.oveyon.com/v1",
      "headers": {
        "Authorization": "Bearer ${input:oveyon-key}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "oveyon-key",
      "description": "Oveyon API key",
      "password": true
    }
  ]
}
```

#### Codex CLI

Em `~/.codex/config.toml`. Antes, exporte `OVEYON_API_KEY` no ambiente.

**~/.codex/config.toml**

```
[mcp_servers.oveyon]
url = "https://mcp.oveyon.com/v1"
bearer_token_env_var = "OVEYON_API_KEY"
```

#### Windsurf

No `mcp_config.json`, aberto pelo próprio editor: Cascade → MCP.

**mcp_config.json**

```
{
  "mcpServers": {
    "oveyon": {
      "serverUrl": "https://mcp.oveyon.com/v1",
      "headers": {
        "Authorization": "Bearer ov_SUA_CHAVE"
      }
    }
  }
}
```

#### Qualquer outro cliente

A URL e o cabeçalho `Authorization`, por Streamable HTTP. Para conferir na mão — a resposta chega como evento, na linha `data:`:

**terminal** tools/list

```
curl -X POST https://mcp.oveyon.com/v1 \
  -H "Authorization: Bearer ov_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

Exemplos

### O que você digita, e o que o agente faz.

Sem API para aprender: o agente escolhe a ferramenta e os argumentos. Alguns pedidos, e as ferramentas por trás deles.

| Você digita | O agente chama | O que acontece |
| --- | --- | --- |
| «De quais domínios eu posso enviar?» | list_domains | Ele lista os domínios da conta. |
| «Envie o e-mail de boas-vindas para ana@exemplo.com, de ola@seudominio.com.br — segure para eu aprovar.» | send_email | Com `hold: true` e uma `idempotencyKey`: o e-mail vira um rascunho que uma pessoa aprova em Mensagens → Aprovações, e repetir nunca envia duas vezes. |
| «O que chegou em suporte@ hoje? Marque o que o veredito de segurança disser que é perigoso.» | list_inbound get_inbound | `list_inbound` com o filtro `agent_safety`, e `get_inbound` no que ele abrir: toda mensagem traz o veredito — clean, suspicious ou dangerous —, com o score e os sinais. |
| «Responda à última mensagem de joao@exemplo.com dizendo que recebemos.» | reply_inbound | Uma resposta em texto puro, da caixa que recebeu a mensagem. Com a trava ligada, ela espera aprovação como qualquer envio. |
| «Que conta e que chave da Oveyon eu estou usando, e o que ela pode fazer?» | whoami | A conta, a chave, as ferramentas que ela pode chamar e o escopo que cada uma das outras exige. |

Segurança

### O agente trabalha dentro da chave, não em volta dela.

Um e-mail recebido pode trazer ordens escondidas. Os freios moram na chave e na plataforma — não no prompt.

#### Os escopos decidem as ferramentas

O servidor lista só o que os escopos da chave liberam: uma chave só de leitura só lê. A chave sugerida não tem `approve:holds` — a chave que envia não é a que aprova.

#### Aprovação humana em todo envio

Criada pela tela do MCP, a chave vem com «Exigir aprovação humana para os envios desta chave» marcada: uma política de envio transforma todo e-mail e toda resposta do agente num rascunho que uma pessoa aprova em Mensagens → Aprovações.

#### O veredito em toda mensagem

Toda mensagem recebida traz o `agentSafety`: clean, suspicious ou dangerous, score de 0 a 100 e os sinais. Um e-mail pode dar ordens ao agente; a aprovação é o que o impede de obedecer.

#### A chave fora do repositório

O painel nunca imprime a chave: ela aparece uma única vez, ao ser criada. Guarde-a na configuração do cliente ou numa variável de ambiente — nunca num repositório.

#### 403 para, 429 espera

Os erros chegam inteiros ao modelo — código, mensagem, `Retry-After`: no 429 o agente espera; no 403 ele para e avisa você.

#### Toda chamada no registro

Cada chamada de ferramenta é uma chamada à API com a mesma chave — escopos, cotas, políticas e idempotência valem — e aparece no Registro de chamadas com a família `oveyon-mcp`.

As ferramentas

### As ferramentas, por escopo.

Cada ferramenta é uma rota da API e exige o escopo dessa rota. O servidor lista só o que a chave libera.

| Escopo | Ferramentas |
| --- | --- |
| send | `send_email` |
| read:messages | `list_messages`, `get_message` |
| read:stats | `get_stats` |
| read:suppressions | `list_suppressions` |
| write:suppressions | `add_suppression`, `remove_suppression` |
| read:domains | `list_domains` |
| write:domains | `add_domain`, `verify_domain` |
| manage:webhooks | `list_webhooks`, `create_webhook`, `update_webhook`, `delete_webhook` |
| read:inbound | `list_inbound`, `get_inbound`, `get_inbound_content`, `list_threads`, `get_thread`, `get_inbound_stats` |
| reply:inbound | `reply_inbound` |
| write:inbound | `release_inbound`, `list_mailboxes`, `create_mailbox`, `get_mailbox`, `update_mailbox`, `delete_mailbox`, `detach_mailbox_channel` |
| approve:holds | `list_holds`, `approve_hold`, `reject_hold` |
| read:templates | `list_templates`, `get_template` |
| write:templates | `create_template`, `update_template`, `publish_template`, `delete_template` |
| read:send-policies | `list_send_policies`, `get_send_policy`, `list_send_policy_decisions` |
| write:send-policies | `create_send_policy`, `update_send_policy`, `pause_send_policy`, `unpause_send_policy`, `reorder_send_policies`, `delete_send_policy` |
| read:inbound-policies | `list_inbound_policies`, `get_inbound_policy`, `list_inbound_policy_decisions`, `simulate_inbound_policy` |
| write:inbound-policies | `create_inbound_policy`, `update_inbound_policy`, `pause_inbound_policy`, `unpause_inbound_policy`, `reorder_inbound_policies`, `delete_inbound_policy` |
| read:policies | `list_allow_block`, `list_ip_rules` |
| write:policies | `add_allow_block`, `remove_allow_block`, `add_ip_rule`, `remove_ip_rule`, `pause_ip_fence`, `unpause_ip_fence` |
| read:surveys | `list_surveys`, `get_survey`, `list_survey_responses` |
| write:surveys | `create_survey`, `update_survey`, `delete_survey` |
| send:surveys | `send_survey` |
| read:logs | `list_api_logs`, `get_api_log` |
| sem escopo (pública) | `check_disposable` |
| toda chave | `whoami` |

Sugeridos para a chave de um agente, e já marcados no painel: `send`, `read:messages`, `read:stats`, `read:suppressions`, `read:domains`, `read:inbound`, `reply:inbound`, `read:templates`, `read:inbound-policies` — sem `approve:holds` (a chave que envia não é a que aprova) e sem `read:logs`.

Perguntas

### Respostas curtas.

#### Custa a mais?

Não. O servidor MCP está incluído em todos os planos, inclusive no gratuito. Ele usa a sua chave de API, e o que o agente envia conta na cota do plano, como sempre.

#### Quais clientes conectam?

Claude Code, Cursor, VS Code, Codex CLI e Windsurf conectam direto; o Claude Desktop conecta pela ponte mcp-remote. Qualquer outro cliente que fale Streamable HTTP e mande o cabeçalho `Authorization` também funciona.

#### O meu cliente não tem campo para cabeçalho. Ele conecta?

A conexão desta página é pela chave de API, no cabeçalho `Authorization: Bearer`. O Claude Desktop conecta pela ponte mcp-remote, que manda o cabeçalho por ele — e o mesmo vale para qualquer cliente que consiga rodar um comando local.

#### O agente pode enviar sem uma pessoa ver?

Só se você deixar. Com «Exigir aprovação humana para os envios desta chave» — marcada quando a chave é criada pela tela do MCP —, todo e-mail e toda resposta viram um rascunho que uma pessoa aprova em Mensagens → Aprovações. Sem `approve:holds`, o agente não aprova os próprios rascunhos.

#### Ele lê anexos e responde com arquivos?

O agente lê a mensagem com `get_inbound_content`; o .eml bruto e os bytes dos anexos não são ferramentas. O `reply_inbound` manda uma resposta em texto puro, sem anexos, da caixa que recebeu a mensagem. O `send_email` aceita anexos (base64) e templates.

#### Onde vejo o que o agente fez?

No Registro de chamadas: toda chamada de ferramenta é uma chamada à API feita com a chave do agente, e aparece lá com a família `oveyon-mcp`.

#### Eu já uso https://api.oveyon.com/v1/mcp. Preciso trocar?

Não. O endereço antigo também funciona e continua funcionando.

### Conecte o seu agente hoje. A trava de aprovação vem junto.

MCP incluído em todos os planos, inclusive no gratuito.

[Criar conta grátis](https://app.oveyon.com/app)
[Documentação](https://api.oveyon.com/?lang=pt)

---

Primeiro envio hoje. Sem cartão. — https://app.oveyon.com/app