# MCP e agentes de IA

> O servidor MCP remoto do Couryo em mcp.couryo.com, as ferramentas send_email, get_email, domain_health e why_bounced, e como conectar no Claude, no Cursor e no ChatGPT.

Fonte: https://couryo.com/docs/mcp

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

| Ferramenta | Escopo | O que faz |
|---|---|---|
| `send_email` | `send` | envia um e-mail de um domínio verificado: `from`, `to` (texto ou lista), `subject`, `html` e/ou `text`, `stream` e `idempotency_key` opcional (24 horas, como o cabeçalho `Idempotency-Key`) |
| `get_email` | `read` | traz um e-mail (`id`, `msg_...`) e a linha do tempo, com código SMTP, resposta original e explicação em linguagem simples |
| `domain_health` | `read` | confere no DNS real o DKIM, o return path e o DMARC de um domínio do projeto (`domain`) e resume o que corrigir |
| `why_bounced` | `read` | explica por que um e-mail (`email_id`) voltou, foi adiado ou recebeu reclamação, e o que fazer |

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](https://couryo.com/docs/errors.md).

### 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](https://couryo.com/docs/test-mode.md#enderecos-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

```bash title="Terminal"
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`:

```json title="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):

```json title=".cursor/mcp.json"
{
  "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.

```python title="Python (API da OpenAI)"
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:

```bash title="cURL"
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](https://couryo.com/llms.txt) e [llms-full.txt](https://couryo.com/llms-full.txt), em português, e as versões em inglês em [/en/llms.txt](https://couryo.com/en/llms.txt).
- Toda página desta documentação em Markdown: acrescente `.md` ao endereço, como em [/docs/sending.md](https://couryo.com/docs/sending.md.md).
- Preços em Markdown, em [/precos.md](https://couryo.com/precos.md) e [/pricing.md](https://couryo.com/pricing.md).

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

```text title="Prompt"
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.
```