Servidor MCP

Conectar agentes de IA à Asender pelo Model Context Protocol: endereço, autenticação e ferramentas.

Servidor MCP

A Asender tem um servidor MCP (Model Context Protocol) remoto. Com ele, um agente de IA (Claude, ChatGPT, Cursor, VS Code e outros clientes MCP) consulta os dados da sua conta: leads, formulários, campanhas, relatórios, conversas e mais. Com chave de API e o escopo certo, o agente também escreve: envia um e-mail e cria ou atualiza leads (veja Ferramentas de escrita). Token OAuth continua somente leitura.

• URL: https://api.asender.net/mcp
• Transporte: Streamable HTTP stateless (um POST por mensagem JSON-RPC; sem SSE e sem sessão)
• Versões do protocolo aceitas: 2025-11-25, 2025-06-18 e 2025-03-26
• Autenticação: chave de API sk_* ou token OAuth de um app, no header Authorization: Bearer
• Ferramentas: 32 (veja o catálogo): 27 de leitura que servem a chave e o token OAuth, 2 de leitura de DNS e 3 de escrita, estas 5 só para chave sk_*

Status

O registro automático está descrito em Aplicativos. O que ainda não existe está em Limites e o que vem a seguir.

Conectar um cliente

A configuração exata muda de cliente para cliente e de versão para versão. Em todos os casos você informa a URL https://api.asender.net/mcp. Clientes com OAuth se registram sozinhos e abrem a tela de consentimento da Asender; nos demais, informe o header Authorization: Bearer sk_live_.... Crie a chave em Chaves de API com só os escopos de leitura de que o agente precisa.

Claude Code

claude mcp add --transport http asender https://api.asender.net/mcp \
  --header "Authorization: Bearer sk_live_..."

Claude (claude.ai e Claude Desktop)

Em Configurações > Conectores, adicione um conector personalizado (Custom connectors) e informe a URL https://api.asender.net/mcp. O cliente se registra sozinho e você autoriza na tela de consentimento da Asender (selo Não verificado até a equipe verificar o cliente). Se preferir, abra as configurações avançadas do conector e informe o client_id de um app cadastrado (e o segredo, se for um app confidencial). Esse caminho não oferece um campo para o header com a chave sk_*; para usar a chave, conecte pelo Claude Code.

ChatGPT

Ative o modo desenvolvedor e adicione um conector (app) MCP remoto com a URL https://api.asender.net/mcp. A autenticação é por OAuth: o ChatGPT se registra sozinho (CIMD ou DCR) e você autoriza na tela de consentimento da Asender; se a sua versão permitir, também dá para informar o client_id de um app cadastrado.

Cursor

No mcp.json do Cursor, declare um servidor com url e headers:

{
  "mcpServers": {
    "asender": {
      "url": "https://api.asender.net/mcp",
      "headers": { "Authorization": "Bearer ${env:ASENDER_API_KEY}" }
    }
  }
}

VS Code

No mcp.json do VS Code, declare um servidor do tipo http:

{
  "servers": {
    "asender": {
      "type": "http",
      "url": "https://api.asender.net/mcp",
      "headers": { "Authorization": "Bearer ${input:asender-key}" }
    }
  },
  "inputs": [
    { "type": "promptString", "id": "asender-key", "description": "Chave de API da Asender", "password": true }
  ]
}

MCP Inspector

npx @modelcontextprotocol/inspector

Escolha o transporte Streamable HTTP, informe a URL https://api.asender.net/mcp e adicione o header Authorization: Bearer sk_live_... (ou use o fluxo OAuth do Inspector, que se registra sozinho). O Inspector, que roda em http://localhost:6274, passa pela verificação de Origin.

Qualquer outro cliente

Adicione um servidor MCP remoto HTTP (Streamable HTTP) com a URL https://api.asender.net/mcp e o header Authorization: Bearer <chave sk_*>. O servidor não usa SSE: um cliente que só fale SSE não conecta.

Autenticação

O servidor é um resource server OAuth 2.1 e também aceita chave de API.

Chave de API

Envie Authorization: Bearer sk_live_.... Valem os escopos da chave: a ferramenta só aparece e só roda se a chave tem o escopo dela. Uma chave sem escopo de leitura enxerga no máximo asender_account_get.

OAuth (app)

1. Descoberta. Uma chamada sem credencial recebe 401 com WWW-Authenticate: Bearer resource_metadata="https://api.asender.net/.well-known/oauth-protected-resource/mcp".
2. O cliente lê esse documento (RFC 9728), que lista em authorization_servers o servidor de autorização https://auth.asender.net, os scopes_supported e o link desta documentação.
3. Em https://auth.asender.net/.well-known/oauth-authorization-server (RFC 8414) estão os endpoints de autorização, de token e de revogação, além do registration_endpoint (https://auth.asender.net/register, DCR) e de client_id_metadata_document_supported: true (CIMD).
4. Registro. O cliente que ainda não tem client_id se registra: publica um documento de metadados e usa a URL dele como client_id (CIMD) ou faz POST /register (DCR, RFC 7591). O cliente nasce público (PKCE, sem segredo), Não verificado e só com escopos de leitura. Os formatos estão em Aplicativos.
5. O cliente abre /authorize com PKCE S256 (obrigatório) e o parâmetro resource=https://api.asender.net/mcp (RFC 8707). O resource faz o token nascer com aud do MCP. Um resource fora da lista permitida é recusado com invalid_target.
6. O usuário entra, escolhe a conta e aprova os escopos na tela de consentimento, que mostra o selo Não verificado e o domínio do cliente até a equipe Asender verificá-lo. Um token vale para um usuário e uma conta. Para trocar de conta, autorize de novo.
7. O cliente troca o code em /token e chama /mcp com o token. O token de acesso dura 15 minutos e é renovado com refresh token.

Clientes públicos (sem segredo, como apps de desktop) usam PKCE sem client_secret e podem usar redirect de loopback (http://127.0.0.1 ou http://[::1], com porta qualquer), conforme a RFC 8252.

Escopos

O token OAuth só exerce leitura; as ferramentas de escrita (email:send, leads:write) nunca aparecem para ele, mesmo que o token traga o escopo. Escopos disponíveis: account:read, leads:read, conversions:read, forms:read, analytics:read, campaigns:read, email:read, messaging:read, conversations:read, journeys:read, logs:read e openid (identidade do usuário que autorizou). Escopo de envio nunca vale para token OAuth. Para chave, valem os escopos da própria chave, descritos em Chaves de API.

Token do MCP e a API REST

Um token com aud só https://api.asender.net/mcp não vale na API REST (/v1): recebe 401. O inverso funciona: um token emitido sem resource, com aud https://api.asender.net, também é aceito no /mcp.

Catálogo de ferramentas

As de leitura anunciam readOnlyHint: true; as 3 de escrita estão em Ferramentas de escrita (readOnlyHint: false). Ferramenta cujo escopo a credencial não tem não aparece em tools/list, e chamá-la diretamente devolve erro. Além do escopo, a conta precisa ter o produto correspondente: sem ele a chamada falha como a REST falharia.

Datas aceitam instante RFC 3339 (por exemplo 2026-10-01T00:00:00Z); nos relatórios e no analytics também YYYY-MM-DD. limit vai de 1 a 200 (padrão 50). A conta é sempre a da credencial: não há argumento de conta.

Ferramentas de escrita

São três e só aparecem em tools/list para uma chave sk_* que tenha o escopo (email:send para o e-mail, leads:write para os leads). Chamá-las sem o escopo, ou com token OAuth, devolve isError. Cada uma roda o mesmo handler da API REST (POST /v1/emails/send, POST /v1/leads, PATCH /v1/leads/{id}): mesmas validações, mesmo corpo fechado (argumento desconhecido é recusado), a conta é sempre a da chave.

Todas têm readOnlyHint: false. As anotações são dicas ao cliente (por exemplo, para pedir confirmação ao usuário), não uma garantia de segurança: quem protege é o escopo da chave.

Idempotência. Toda escrita leva um Idempotency-Key:

• Se você passa o argumento idempotency_key (1 a 128 caracteres de [A-Za-z0-9._:-]), ele é a chave. Repetir a chamada com a mesma chave e os mesmos argumentos devolve o mesmo resultado sem escrever de novo; a mesma chave com argumentos diferentes é recusada (422 IdempotencyKeyReused).
• Se omite, o servidor deriva a chave dos argumentos (mcp: + hash do nome da ferramenta, da conta e dos argumentos, sem importar a ordem). Assim, um agente que repete a mesma chamada (timeout, retry do cliente, modelo que insiste) não envia dois e-mails nem cria dois leads. Para reenviar de propósito a mesma coisa, passe um idempotency_key diferente. A janela de deduplicação é a do dono do dado (24 h nos leads).

Exemplo (enviar um e-mail):

curl -s https://api.asender.net/mcp \
  -H "Authorization: Bearer $ASENDER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"asender_emails_send","arguments":{"from":"contato@exemplo.com","to":["cliente@exemplo.org"],"subject":"Seu pedido","text":"Obrigado pela compra.","idempotency_key":"pedido-1042-aviso"}}}'

Formato da resposta

Uma chamada com sucesso devolve o mesmo JSON da API REST em duas formas: em content (um bloco text com o JSON) e em structuredContent (o objeto). Uma resposta acima de 1 MiB é recusada com a orientação de reduzir limit, usar cursor ou estreitar a janela de tempo.

Erros

• Erro de negócio (argumento inválido, escopo ou produto ausente, 404, 429, 5xx da rota) não é erro JSON-RPC: volta como resultado com isError: true e um texto como HTTP 404 Not Found: ..., para o modelo se corrigir.
• Erro de protocolo usa os códigos JSON-RPC: -32700 (JSON inválido), -32600 (pedido inválido), -32601 (método inexistente) e -32602 (parâmetros inválidos ou ferramenta desconhecida).
• Erro de transporte: 401 sem credencial válida; 403 para Origin não permitido; 400 para MCP-Protocol-Version desconhecida, lote JSON-RPC ou JSON inválido; 413 acima de 1 MiB; 405 para GET e DELETE.

Paginação

As listas devolvem next_cursor quando há mais itens. Para a próxima página, repita a chamada passando esse valor em cursor (valor opaco: não o monte nem o interprete). asender_logs_list pagina por after/before, com ids de log.

Exemplos com curl

Defina a chave em uma variável de ambiente:

export ASENDER_API_KEY='sk_live_...'

initialize

curl -s https://api.asender.net/mcp \
  -H "Authorization: Bearer $ASENDER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

A resposta traz protocolVersion, capabilities (tools), serverInfo e as instructions do servidor. Depois do initialize, um cliente completo envia a notificação notifications/initialized (resposta 202 sem corpo); com curl isso é opcional, porque o servidor não guarda sessão.

tools/list

curl -s https://api.asender.net/mcp \
  -H "Authorization: Bearer $ASENDER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Só aparecem as ferramentas que a chave pode usar.

tools/call

curl -s https://api.asender.net/mcp \
  -H "Authorization: Bearer $ASENDER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"asender_leads_list","arguments":{"limit":10}}}'

Para a página seguinte, repita com "arguments":{"limit":10,"cursor":"<next_cursor>"}.

Segurança

• Origin. Chamadas de navegador de um site que não seja da Asender recebem 403. Clientes de servidor e de linha de comando não enviam Origin e passam; loopback (localhost, como o MCP Inspector) é aceito.
• CORS. Liberado para qualquer origem sem credenciais (Access-Control-Allow-Origin: *), o que deixa um cliente web ler o WWW-Authenticate do 401. A autenticação é só pelo header Authorization, nunca por cookie.
• Limite de taxa. O /mcp tem limite de taxa; ao exceder, a ferramenta devolve isError com HTTP 429. Reduza a frequência das chamadas.
• Acesso por conta. Além do escopo, a Asender confere a cada chamada que o usuário do token ainda tem acesso àquela conta e àquele produto. Quem perde o acesso à conta perde o acesso do app em até 60 segundos.
• Revogação. O usuário revoga o acesso de um app na tela Apps conectados do login da Asender; a chave de API é revogada no painel, em Chaves de API.
• Token só do MCP. O aud do token o amarra ao recurso: um token do /mcp não funciona na REST.
• Prompt injection. O conteúdo que o agente lê, como nome, e-mail, mensagem de lead, resposta de formulário ou texto de conversa, vem de terceiros e deve ser tratado como dado não confiável. Um texto de lead que diga "ignore as instruções anteriores" não é uma ordem para o modelo. Com as ferramentas de escrita (e-mail e leads) o risco é real: um lead ou uma conversa podem tentar induzir o agente a enviar e-mail ou alterar dados. Por isso o token OAuth não escreve, a escrita exige chave com escopo próprio e, no cliente, vale exigir confirmação humana antes de asender_emails_send (ele anuncia openWorldHint: true).
• Menor privilégio. Para o agente, crie uma chave só com os escopos de que ele precisa (de preferência só leitura; email:send e leads:write apenas se o agente realmente escreve) e use uma chave por integração, para revogar sem derrubar o resto.

Limites e o que vem a seguir

• Escrita só com chave e só em 3 ferramentas. Há e-mail transacional e criar/atualizar lead. Não há ferramenta para SMS, WhatsApp ou push, apagar lead, nem escrita por token OAuth (leads:write segue não concedível a apps).
• Só tools. O servidor não expõe resources nem prompts ainda, e não envia notificações (listChanged é falso).
• Sem stream. Não há SSE nem sessão (Mcp-Session-Id); GET /mcp responde 405. Não há lote JSON-RPC.
• Clientes registrados automaticamente são "Não verificados". Recebem só escopos de leitura e exibem o aviso na tela de consentimento até a equipe Asender verificá-los; a equipe também pode suspender um cliente ou bloquear um domínio.
• Uma conta por conexão. Para consultar outra conta, conecte de novo escolhendo a outra conta (ou use outra chave).