MCP and AI agents

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#

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.

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 (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#

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:

{
  "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):

{
  "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.

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:

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 and llms-full.txt in English, with Portuguese versions at /llms.txt.
• Every page of this guide as Markdown: add .md to the URL, as in /en/docs/sending.md.
• Pricing as Markdown at /pricing.md.

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

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