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.
Incluído em todos os planos, inclusive no gratuito · Claude Code, Claude Desktop, Cursor, VS Code, Codex CLI, Windsurf
# 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;
whoamiecheck_disposablevalem 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://guidetraz 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.
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.
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.
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.
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:
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.
{
"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.
{
"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.
{
"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.
[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.
{
"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::
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.