MCP server

Connect AI agents to Bytesms through the remote MCP server with OAuth.

Bytesms runs a remote Model Context Protocol server, so AI agents and coding assistants can send email, look up delivery status and manage domains and API keys for you.

Server URL

https://api.bytesms.com/api/mcp

Connect a client

Most clients only need the URL: they discover the OAuth server, open a Bytesms consent screen where you pick the workspace and the access level, and store the token.

claude mcp add --transport http bytesms https://api.bytesms.com/api/mcp
# then run /mcp inside Claude Code to sign in

Claude (claude.ai / desktop): add a custom connector with the server URL. Step-by-step instructions per client are also in Dashboard → Settings → Integrations → MCP.

Authentication

OAuth 2.1 (recommended)

Discovery: /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server on api.bytesms.com (no /api prefix). Dynamic client registration, authorization code with PKCE (S256).
Scopes: full (every tool) or sending (only send_email). The access level is confirmed on the consent screen.
Access tokens last 1 hour; refresh tokens 30 days and rotate on use.
A grant is bound to one workspace. Revoke it any time in Dashboard → Settings → Integrations → MCP.

API key

Clients that can send custom headers may use an API key instead: Authorization: Bearer tp_live_…. A sending_access key only sees send_email.

Header-based config (example)

{
  "mcpServers": {
    "bytesms": {
      "url": "https://api.bytesms.com/api/mcp",
      "headers": {
        "Authorization": "Bearer tp_live_xxxxxxxxx"
      }
    }
  }
}

Tools

Tool	Access	What it does
`send_email`	full, sending	Send an email: from, to, subject, html/text, cc, bcc, reply_to, scheduled_at.
`list_emails`	full	List emails, newest first (page, limit ≤ 100, status filter).
`get_email`	full	One email with its delivery events.
`list_domains`	full	Domains and their verification status.
`get_domain`	full	A domain with the DNS records to publish.
`create_domain`	full	Add a domain (name, optional region).
`verify_domain`	full	Start or re-run DNS verification.
`delete_domain`	full	Remove a domain.
`list_api_keys`	full	API keys (prefix only).
`create_api_key`	full	Create a key (permission, optional domain_id). The key is returned once.
`remove_api_key`	full	Revoke a key.

Tools call the same services as the REST API, so the sending rules, quotas, plan limits and domain scoping are identical.

Protocol details

Streamable HTTP transport, stateless: each POST carries one JSON-RPC message and gets a JSON response. There is no SSE stream and no session (GET/DELETE return 405); JSON-RPC batches are not supported.
tools/call shares the workspace's API rate limit; over the limit the response is HTTP 429 with a JSON-RPC error and a retry-after header.
An invalid or expired token gets 401 with a WWW-Authenticate header pointing to the resource metadata.
MCP calls appear in the workspace's request logs.

Agents act with your permissions

Give agents the least access they need — the sending scope or a domain-scoped sending key is usually enough — and review what they send.