MCP over HTTP
For building a client, or calling Angel Mail from code without an MCP library.
The endpoint #
POST https://app.angelmail.io/mcp (your own server: https://<your server>/mcp)
Content-Type: application/json
Authorization: Bearer smt_… (or the access token from sign-in)
Streamable HTTP, stateless: each POST carries one JSON-RPC 2.0 message (or a batch array) and gets a JSON reply. There is no server-sent event stream and no session id. Notifications (no id) get 202 Accepted and no body. Protocol versions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05 are accepted; the server answers with the one you asked for, else the newest.
Signing in, or a token #
Tokens. Make one in Angel Mail → Settings → AI connections → Any other MCP client. It starts with smt_, works only for this server, and only until the owner revokes it. Its name is what the owner sees on everything it writes.
Sign-in (OAuth 2.1). A request without a working token gets 401 with WWW-Authenticate pointing at the protected-resource metadata:
GET /.well-known/oauth-protected-resource/mcp
GET /.well-known/oauth-authorization-server (also /.well-known/openid-configuration)
Clients register at /oauth/register (dynamic client registration), send the owner to /oauth/authorize with PKCE, and exchange the code at /oauth/token, which also refreshes. Sign-in is open only to known apps: callbacks on this computer (loopback), the app schemes cursor://, vscode://, vscode-insiders:// and windsurf://, and the https callbacks of Claude, ChatGPT, Grok, Cursor and VS Code. Any other app connects with a token.
The calls #
Start a connection:
curl -s https://app.angelmail.io/mcp -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25"}}'
{"jsonrpc": "2.0", "id": 1, "result": {
"protocolVersion": "2025-11-25",
"capabilities": {"tools": {"listChanged": false}, "prompts": {"listChanged": false}},
"serverInfo": {"name": "angel-mail", "title": "Angel Mail", "version": "0.4.0"},
"instructions": "Angel Mail: the owner's email across their linked inboxes. …"}}
Show instructions to the model: they carry the rules for drafting and sending.
| Method | What it does |
|---|---|
initialize | Capabilities, server info, instructions |
ping | {} |
tools/list | Every tool this token may use, with input schemas and annotations (send_approved_email only for tokens that may send) |
tools/call | {"name": "<tool>", "arguments": {…}} |
prompts/list | The named workflows and their arguments |
prompts/get | {"name": "<workflow>", "arguments": {…}}: one user message with the steps |
Call a tool:
curl -s https://app.angelmail.io/mcp -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_mail","arguments":{"query":"is:unread newer_than:2d","limit":5}}}'
Results come twice: as structuredContent (the JSON object) and as content[0].text (the same JSON as text, for clients that only read text). Read structuredContent when your client supports it.
Get a workflow:
curl -s https://app.angelmail.io/mcp -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":3,"method":"prompts/get","params":{"name":"draft_replies","arguments":{"limit":"3"}}}'
{"jsonrpc": "2.0", "id": 3, "result": {"description": "Find conversations waiting for …",
"messages": [{"role": "user", "content": {"type": "text", "text": "Draft replies for … at most 3.\n1. Call get_writing_feedback …"}}]}}
Errors #
A tool that fails returns a normal result with isError: true and the reason as text, so the model can read it and try again:
{"result": {"isError": true, "content": [{"type": "text", "text": "Error: No such item among yours (list_my_drafts shows them)"}]}}
Everything else is an HTTP status or a JSON-RPC error:
| Answer | Meaning | What to do |
|---|---|---|
HTTP 401, error -32001 | No token, or the token was refused | Sign in again, or make a new token |
HTTP 403, error -32002 | The owner switched this agent off in Settings → AI connections | Tell the owner; it works again once they switch it back on. Don't start a new sign-in |
HTTP 404, error -32001 | A public demo with agents switched off | Use your own server or the hosted service |
| HTTP 429 | Too many requests; Retry-After says how many seconds to wait | Wait, then try again |
HTTP 400, error -32700 | The body isn't JSON | Fix the request |
error -32601 | Unknown method | Check the method name |
error -32602 | Unknown tool or prompt, or a missing prompt argument | Check tools/list or prompts/list |
| HTTP 405 on GET | There is no event stream (with a working token; without one, a GET gets the same 401 as a POST) | Use POST |
Limits #
| What | Limit |
|---|---|
Requests to /mcp | 600 a minute from one address (a server can change it) |
Sending (approving an email, send_approved_email) | 300 an hour per owner |
| A request body | About 4 MB, so put big files at a public https URL |
| Attachments on one email | 25 MB in total (Gmail's limit) |
wait_for_review | Up to 50 seconds per call |
search_mail | Up to 40 conversations per call |
propose_actions | Up to 100 items per batch |
| A skill's ticket | 2 hours |
send_approved_email | Within 2 hours of the request_send |