# MCP and AI agents

> Couryo's remote MCP server at mcp.couryo.com, the send_email, get_email, domain_health and why_bounced tools, and how to connect from Claude, Cursor and ChatGPT.

Source: https://couryo.com/en/docs/mcp

Couryo runs a remote MCP server at `https://mcp.couryo.com`. With it, your AI agent sends email, reads a message's timeline, checks a domain's DNS and explains why an email bounced, just by chatting.

- **Transport:** Streamable HTTP, stateless.
- **Sign-in:** the same API key as the REST API, in the `Authorization: Bearer ck_...` header, with the same scopes and the key's project.
- **OAuth:** coming soon. With it, the Claude and ChatGPT connectors will sign in without pasting any key.

## Tools

| Tool | Scope | What it does |
|---|---|---|
| `send_email` | `send` | sends an email from a verified domain: `from`, `to` (string or list), `subject`, `html` and/or `text`, `stream` and an optional `idempotency_key` (24 hours, like the `Idempotency-Key` header) |
| `get_email` | `read` | returns an email (`id`, `msg_...`) and its timeline, with SMTP code, raw response and a plain-language explanation |
| `domain_health` | `read` | checks a project domain's DKIM, return path and DMARC in real DNS (`domain`) and summarizes what to fix |
| `why_bounced` | `read` | explains why an email (`email_id`) bounced, was deferred or got a complaint, and what to do |

Responses and error messages follow the `Accept-Language` header (Portuguese by default; send `Accept-Language: en` for English). Errors use the same shape and codes as the [API](https://couryo.com/en/docs/errors.md).

### Which key to use

- A `send` key can only use `send_email`; a `read` key only the three read tools. For all four, use an `admin` key.
- Start with a `ck_test_` key: nothing is delivered, and the [simulated addresses](https://couryo.com/en/docs/test-mode.md#simulated-addresses) (`bounced@`, `complained@`, `deferred@`) let the agent try `why_bounced` for real.
- The key lives in the MCP client's configuration on your machine. Do not paste it into the chat.

## Claude Code

```bash title="Terminal"
claude mcp add --transport http couryo https://mcp.couryo.com \
  --header "Authorization: Bearer $COURYO_API_KEY"
```

Then just ask: "why did email msg_... bounce?" or "is example.com's DNS right?".

## Claude Desktop

Until OAuth lands, Claude Desktop connects through the `mcp-remote` bridge, which forwards the header with your key. Under **Settings > Developer > Edit config**, in `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_..." }
    }
  }
}
```

Restart Claude Desktop. The connector through **Settings > Connectors** (and on claude.ai) depends on OAuth: coming soon.

## Cursor

Under **Settings > MCP**, or in the project's `.cursor/mcp.json` file (`~/.cursor/mcp.json` for every project):

```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "couryo": {
      "url": "https://mcp.couryo.com",
      "headers": { "Authorization": "Bearer ${env:COURYO_API_KEY}" }
    }
  }
}
```

Do not commit the key: use the environment variable, as above.

## ChatGPT

- **ChatGPT app (connectors):** requires OAuth. It arrives with Couryo's OAuth (coming soon).
- **OpenAI API:** works today, with the remote MCP tool and the key header.

```python title="Python (OpenAI API)"
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="Why did email msg_9w2k7c1x0d4e5f6g bounce?",
)
print(resp.output_text)
```

## Try it by hand

The server answers JSON-RPC over `POST`. To list the tools:

```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": {} }'
```

Without a key, or with an invalid one, the answer is `401` with the `missing_api_key` or `invalid_api_key` error.

## Coming soon

- OAuth for the Claude and ChatGPT connectors, with no key to paste.
- More tools: delivery diagnosis by provider, DNS setup, suppressions, templates and received replies. Every action that changes something will have a test mode and ask for confirmation.

## Docs for agents

- [llms.txt](https://couryo.com/en/llms.txt) and [llms-full.txt](https://couryo.com/en/llms-full.txt) in English, with Portuguese versions at [/llms.txt](https://couryo.com/llms.txt).
- Every page of this guide as Markdown: add `.md` to the URL, as in [/en/docs/sending.md](https://couryo.com/en/docs/sending.md.md).
- Pricing as Markdown at [/pricing.md](https://couryo.com/pricing.md).

To have your coding agent write the integration, point it at `llms-full.txt`:

```text title="Prompt"
Read https://couryo.com/en/llms-full.txt and integrate order confirmation emails
with the Couryo API, using Idempotency-Key and verifying webhook signatures.
```