MCP e agentes de IA

O Couryo tem um servidor MCP remoto em https://mcp.couryo.com. Com ele, o seu agente de IA envia e-mails, consulta a linha do tempo de uma mensagem, confere o DNS de um domínio e explica por que um e-mail voltou, conversando.

• Transporte: Streamable HTTP, sem estado.
• Entrada: a mesma chave de API da REST, no cabeçalho Authorization: Bearer ck_..., com os mesmos escopos e o mesmo projeto da chave.
• OAuth: em breve. Com ele, os conectores do Claude e do ChatGPT vão entrar sem colar chave nenhuma.

Ferramentas#

As respostas e as mensagens de erro saem no idioma do cabeçalho Accept-Language (português por padrão). Os erros têm o mesmo formato e os mesmos códigos da API.

Qual chave usar#

• Uma chave send só usa send_email; uma chave read só usa as três de leitura. Para as quatro, use uma chave admin.
• Comece com uma chave ck_test_: nada é entregue, e os endereços simulados (bounced@, complained@, deferred@) deixam o agente testar o why_bounced de verdade.
• A chave fica na configuração do cliente MCP, na sua máquina. Não cole a chave na conversa.

Claude Code#

claude mcp add --transport http couryo https://mcp.couryo.com \
  --header "Authorization: Bearer $COURYO_API_KEY"

Depois, peça em linguagem natural: "por que o e-mail msg_... voltou?" ou "o DNS de exemplo.com.br está certo?".

Claude Desktop#

Até o OAuth chegar, o Claude Desktop conecta pela ponte mcp-remote, que repassa o cabeçalho com a chave. Em Configurações > Desenvolvedor > Editar configuração, no claude_desktop_config.json:

{
  "mcpServers": {
    "couryo": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.couryo.com", "--header", "Authorization:${COURYO_AUTH}"],
      "env": { "COURYO_AUTH": "Bearer ck_live_..." }
    }
  }
}

Reinicie o Claude Desktop. O conector pela tela Configurações > Conectores (e no claude.ai) depende do OAuth: em breve.

Cursor#

Em Settings > MCP, ou no arquivo .cursor/mcp.json do projeto (~/.cursor/mcp.json para todos os projetos):

{
  "mcpServers": {
    "couryo": {
      "url": "https://mcp.couryo.com",
      "headers": { "Authorization": "Bearer ${env:COURYO_API_KEY}" }
    }
  }
}

Não commite a chave: use a variável de ambiente, como acima.

ChatGPT#

• App do ChatGPT (conectores): pede OAuth. Chega junto com o OAuth do Couryo (em breve).
• API da OpenAI: já funciona hoje, com a ferramenta de MCP remoto e o cabeçalho da chave.

import os
from openai import OpenAI

client = OpenAI()
resp = client.responses.create(
    model="gpt-4.1",
    tools=[{
        "type": "mcp",
        "server_label": "couryo",
        "server_url": "https://mcp.couryo.com",
        "headers": {"Authorization": f"Bearer {os.environ['COURYO_API_KEY']}"},
        "require_approval": "always",
    }],
    input="Por que o e-mail msg_9w2k7c1x0d4e5f6g voltou?",
)
print(resp.output_text)

Testar na mão#

O servidor responde JSON-RPC por POST. Para listar as ferramentas:

curl https://mcp.couryo.com \
  -H "Authorization: Bearer $COURYO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} }'

Sem chave, ou com uma chave inválida, a resposta é 401 com o erro missing_api_key ou invalid_api_key.

Em breve#

• OAuth para os conectores do Claude e do ChatGPT, sem colar chave.
• Mais ferramentas: diagnóstico de entrega por provedor, configuração de DNS, supressões, templates e respostas recebidas. Toda ação que muda algo terá modo de teste e pedirá confirmação.

Documentação para agentes#

• llms.txt e llms-full.txt, em português, e as versões em inglês em /en/llms.txt.
• Toda página desta documentação em Markdown: acrescente .md ao endereço, como em /docs/sending.md.
• Preços em Markdown, em /precos.md e /pricing.md.

Para o seu agente de código escrever a integração, aponte para o llms-full.txt:

Leia https://couryo.com/llms-full.txt e integre o envio de e-mail de confirmação de pedido
com a API do Couryo, usando Idempotency-Key e verificando a assinatura dos webhooks.