# MCP over HTTP

For building a client, or calling Angel Mail from code without an MCP library.

## The endpoint

```text
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:

```text
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:

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

```json
{"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](workflows.md) and their arguments |
| `prompts/get` | `{"name": "<workflow>", "arguments": {…}}`: one user message with the steps |

Call a tool:

```bash
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:

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

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

```json
{"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` |
