Samva

O servidor MCP hospedado da Samva permite que agentes de IA enviem e-mails, leiam respostas e gerenciem modelos, domínios, campanhas e caixas de correio por meio de sua API de e-mail.

Ver em samva.dev

Servidor MCP hospedado

npx add-mcp 'https://mcp.samva.dev'

Instala no Claude Code, Codex, Cursor e outros

Documentação

Conecte um agente via MCP

URL: https://samva.dev/docs/developers/mcp

A Samva executa um servidor hospedado do Model Context Protocol (MCP). Uma chave de API ou conexão OAuth concede ao agente ferramentas de e-mail com escopo organizacional por meio desse servidor.

Para o fluxo de trabalho de agentes, consulte API de e-mail para agentes de IA.

Para rotear essas ferramentas por meio de um catálogo compartilhado com políticas de aprovação, consulte Conectar a Samva ao Executor.

Para começar pelo ChatGPT, consulte Usar o plugin no ChatGPT.

Endpoint [#endpoint]


URL	`https://mcp.samva.dev`
Transporte	HTTP transmissível (sem SSE)
Escopo	Uma organização, derivada da sua credencial

Autenticação é obrigatória [#authentication-is-required]

Conecte-se com qualquer um dos tipos de credencial. O servidor não trata um cookie do painel da Samva como autenticação MCP.

Modo	Cabeçalho
Chave de API	`X-API-Key: samva_sk_live_…` ou `Authorization: Bearer samva_sk_live_…`
OAuth	`Authorization: Bearer <jwt>`

Para OAuth, o servidor anuncia a descoberta conforme a RFC 9728. Uma solicitação sem credencial, ou com credencial inválida ou expirada, retorna 401 com um cabeçalho WWW-Authenticate: Bearer resource_metadata="…" apontando para /.well-known/oauth-protected-resource. Um token OAuth está vinculado à única organização que você escolher ao aprovar a conexão. Consulte Autenticação para ambos os tipos de credencial.

A descoberta de ferramentas depende do chamador. Atualize ou reconecte o cliente MCP após adicionar, remover ou alterar uma credencial para que ele não mantenha um catálogo de ferramentas desatualizado.

Perfis de conta conectados [#connected-account-profiles]

profile_get é uma ferramenta autenticada, somente leitura e sem argumentos. Seu descritor inclui _meta["openai/profile"]: true. Ela retorna id, name e nickname para a associação do usuário na organização da conexão. O ID permanece o mesmo em atualizações, reconexões e alterações de nome de exibição; o apelido combina os nomes do usuário e da organização para exibição, não para roteamento.

Use uma conexão separada para cada organização. Selecionar outra conexão não alterna um token existente nem altera a organização ativa do painel. Remover a associação nega o acesso; re-adicionar o usuário cria um novo ID de perfil. Um token existente não expirado pode recuperar o acesso sob as permissões atuais dessa nova associação. Leituras de perfil exigem organization:read para chaves de API restritas e não concedem acesso adicional. A apresentação desses metadados no cliente varia conforme o host.

Usar o plugin no ChatGPT [#use-the-plugin-in-chatgpt]

O plugin publicado da Samva conecta o ChatGPT a este servidor hospedado. Abra o plugin da Samva no ChatGPT, instale-o e aprove a conexão para a única organização que você escolher. A conexão tem o mesmo acesso com escopo organizacional que qualquer cliente OAuth.

Comece com uma verificação somente leitura. Nenhum dos prompts envia e-mail:

Using Samva, check whether this organization is ready to send email and list what is left to set up.
Using Samva, show the status of my most recent email.

Ferramentas que enviam, agendam, publicam ou alteram configurações são gravações. Solicite-as apenas quando você realmente quiser usá-las. As ferramentas listadas pelo ChatGPT dependem do que esse cliente expõe, então use a descoberta de ferramentas em vez de presumir o catálogo completo abaixo. Trabalhe com uma organização por conexão, como Perfis de conta conectados descreve. Qualquer outro cliente MCP que suporte OAuth usa a configuração abaixo.

Configurar seu cliente [#configure-your-client]

Os esquemas de configuração do cliente variam. O formato genérico de HTTP transmissível é:

OAuth

<TabsTrigger value="apikey">
  Chave de API
</TabsTrigger>

Aponte o cliente para a URL MCP hospedada e use a ação de conexão OAuth dele. A descoberta OAuth é publicada na origem do MCP.

```json
{
  "mcpServers": {
    "samva": {
      "type": "http",
      "url": "https://mcp.samva.dev"
    }
  }
}
```

```json { "mcpServers": { "samva": { "type": "http", "url": "https://mcp.samva.dev", "headers": { "X-API-Key": "samva_sk_live_your_api_key" } } } } ```

Famílias de ferramentas disponíveis [#available-tool-families]

O catálogo autenticado inclui estas famílias de ferramentas com escopo organizacional. Use a descoberta de ferramentas MCP para obter o esquema de entrada atual de cada ferramenta.

Família	Ferramentas
Perfil	`profile_get`
Ajuda do Samva	`ask`, `search_templates`
Contatos	`contacts_find_or_create`, `contacts_subscribe`
Mensagens	`messages_send_email`, `messages_get`, `messages_list_email`, `messages_get_email_status`, `messages_list_email_events`
Anexos	`email_attachments_create_upload`, `email_attachments_complete_upload`
Conversas	`conversations_get`
Revisão de e-mail	`email_review_get_status`, `email_review_reapply`
Rastreamento de e-mail	`email_tracking_get_defaults`, `email_tracking_update_defaults`, `email_tracking_get_recipient`, `email_tracking_update_recipient`
Domínios	`email_domains_add`, `email_domains_list`, `email_domains_get`, `email_domains_verify`, `email_domains_check_verification`, `email_domains_get_status`, `email_domains_rotate_dkim`, `email_domains_remove`, `email_domains_enable_receiving`, `email_domains_enable_custom_tracking`, `email_domains_get_custom_tracking`, `email_domains_recheck_custom_tracking`, `email_domains_disable_custom_tracking`
Remetentes	`email_senders_add`, `email_senders_list`, `email_senders_get`, `email_senders_check_verification`, `email_senders_remove`
Aquecimento de domínio	`email_domains_warming_get`, `email_domains_warming_start`, `email_domains_warming_update_policy`, `email_domains_warming_pause`, `email_domains_warming_resume`
Webhooks	`webhooks_create`, `webhooks_list`, `webhooks_get`, `webhooks_update`, `webhooks_delete`, `webhooks_test`, `webhooks_list_logs`, `webhooks_get_stats`, `webhooks_retry_delivery`, `webhooks_rotate_secret`
Uso e comprovação	`usage_get`, `email_get_stats`, `email_check_readiness`, `email_get_launch_proof`
Modelos	`templates_create`, `templates_list`, `templates_add_entry`, `templates_move_entry`, `templates_get`, `templates_open_workspace`, `templates_diff_workspace`, `templates_patch_workspace`, `templates_resolve_workspace_conflict`, `templates_check_workspace`, `templates_render_fixture`, `templates_snapshot_fixture`, `templates_save_workspace`, `templates_workspace_history`, `templates_restore_workspace`, `templates_publish`, `templates_get_publication`
Marcas	`brands_list`, `brands_get`, `brands_update`
E-mail agendado	`scheduled_messages_schedule_email`, `scheduled_messages_list`, `scheduled_messages_get`, `scheduled_messages_cancel`, `scheduled_messages_resume`
Campanhas	`campaigns_create`, `campaigns_update`, `campaigns_list`, `campaigns_get`, `campaigns_archive`, `campaigns_schedule_run`, `campaigns_list_runs`, `campaigns_get_run`, `campaigns_control_run`, `campaigns_list_recipients`
Feedback	`feedback_send`

A superfície MCP inclui totais de uso e leituras de comprovação de e-mail. O status de cobrança, os direitos e as ações do portal de cobrança estão disponíveis pelo painel, não pelo MCP.

email_senders_add requer um idempotencyKey estável. Reutilizar essa chave com entrada idêntica retorna o remetente original; reutilizá-la com entrada diferente gera conflito. Os resultados do remetente mantêm o ciclo de vida do provedor (provisioning, active, deleting ou failed) separado da verificação de caixa de correio (pending, verified ou failed).

Recursos [#resources]

O servidor retorna instruções de operação durante a inicialização e publica estes recursos legíveis:

URI	Conteúdo
`samva://guide/email`	Fluxo de trabalho de e-mail transacional
`samva://guide/template-editor`	Fluxo de trabalho de projeto de modelo TSX e workspace
`samva://guide/scheduling`	Fluxos de trabalho de e-mail agendado e campanhas
`samva://reference/contract`	Contrato de modelo legível por máquina: componentes e suas props, as formas do perfil estático, formatadores e códigos de diagnóstico
`samva://reference/sml`	Referência completa de autoria de modelos de e-mail

Reenviar um envio com segurança [#retry-a-send-safely]

Passe um idempotencyKey estável para messages_send_email quando uma automação puder repetir a solicitação. Uma repetição idêntica retorna o e-mail original. Reutilizar a chave com destinatários, conteúdo, modelo ou variáveis alterados retorna um conflito.

A ferramenta anuncia a anotação MCP estática idempotentHint: false porque a chave é opcional. A anotação não muda para uma chamada com chave. Trate um envio como seguro para repetição somente quando você forneceu a chave.

Anexar um arquivo [#attach-a-file]

Os argumentos da ferramenta são texto que o modelo escreve, então os bytes do arquivo nunca passam por uma chamada de ferramenta. Envie cada arquivo do próprio ambiente do seu agente:

Chame email_attachments_create_upload com o filename, contentType e sizeBytes do arquivo. Ele retorna um mediaId e uma instrução upload.
Envie os bytes exatos do arquivo com o método da instrução para seu url, com cada cabeçalho que ela lista, antes de expiresAt. Por exemplo, curl -X PUT -H "Content-Type: application/pdf" --data-binary @receipt.pdf "$URL".
Chame email_attachments_complete_upload com o mediaId.
Passe attachments: [{ "mediaId": "..." }] para messages_send_email ou scheduled_messages_schedule_email. A URL de upload é uma permissão de escrita de curta duração para aquele arquivo específico, então trate-a como um segredo. Um agente sem shell ou acesso HTTP não pode fazer upload, e a CLI anexa arquivos locais com --attach. Os anexos seguem os limites de anexos de e-mail.

Editar um template com segurança [#edit-a-template-safely]

Comece com templates_list, templates_get ou templates_create, depois abra o workspace do projeto com templates_open_workspace. Então:

Chame templates_diff_workspace quando precisar das alterações exatas em relação à base do workspace.
Chame templates_patch_workspace com expectedRevision e conclua substituições ou exclusões completas de arquivos TSX.
Releia após cada mutação. Reabra com templates_open_workspace para puxar commits externos, depois resolva quaisquer conflitos explícitos com templates_resolve_workspace_conflict.
Execute templates_check_workspace na revisão atual e revise o que o projeto declara e cada achado, depois templates_render_fixture com um dos nomes de fixture que ele relatou. Chame templates_snapshot_fixture com o mesmo fixture para vê-lo nas larguras de desktop e mobile, em claro e escuro.
Chame templates_save_workspace com a revisão mais recente somente após uma solicitação explícita de Salvar.
Use templates_workspace_history para inspecionar commits. templates_restore_workspace prepara uma árvore histórica alcançável como uma nova sobreposição; ele não reescreve o branch.
Chame templates_publish somente após uma solicitação explícita de Publicar. A publicação resultante fixa o projeto, o commit e o caminho de entrada exatos.

Um template é um arquivo TSX no perfil estático que exporta por padrão defineTemplate, e nada nele é executado quando uma mensagem é enviada. Um projeto pode conter vários templates. Para adicionar um, escreva seu arquivo templates/*.tsx (emails/ também é reconhecido) com templates_patch_workspace, depois registre-o com templates_add_entry, usando seu id defineTemplate como o slug. Liste os templates de um projeto com templates_list e seus projectId. Cada template abre o mesmo workspace compartilhado e publica separadamente. Após renomear um arquivo, chame templates_move_entry para que o template mantenha seu id e publicações.

Os arquivos do projeto no repositório Git do template são a fonte autoral. HTML e texto compilados são derivados pela pré-visualização e publicação. Veja O loop do agente para saber como as ferramentas de template mapeiam para a CLI. O MCP hospedado não emite credenciais Git.

Veja Agendar um e-mail e Enviar uma campanha para sequências de ferramentas orientadas a tarefas.

Ferramentas de caixa de entrada [#mailbox-tools]

O mesmo servidor expõe ferramentas para listar caixas de entrada, ler e pesquisar threads, responder e revisar e-mails retidos. Veja Usar caixas de entrada via MCP.

MCP versus Habilidades de Agente [#mcp-versus-agent-skills]

O servidor MCP é execução de ferramenta ao vivo: o agente faz coisas contra o Samva. Uma Habilidade de Agente Samva é instruções: ela ensina um agente a usar o Samva através do SDK, CLI e MCP, e qual superfície alcançar. Elas se complementam.