Choose REST or MCP
REST and MCP call the same implementation and enforce the same permissions. Choose based on your client architecture rather than expected capability.
| Choose | When it fits |
|---|---|
| MCP streamable HTTP | A model host discovers tools, understands structured tool results, and manages an MCP session |
| REST | Your application owns orchestration, HTTP retries, and typed request/response code |
Shared behavior
Section titled “Shared behavior”Both interfaces:
- authenticate with the same bearer JWTs;
- resolve current mailbox grants and token scopes on every request;
- return the same domain objects and error codes;
- call the same 24 granular mailbox tools;
- support the four declarative email operations;
- audit against the same requesting identity.
Differences to account for
Section titled “Differences to account for”| Concern | REST | MCP |
|---|---|---|
| Endpoint | /api/v1/… |
/mcp |
| Declarative names | URL segments email.query, email.act, email.await, email.requests |
Tool names email_query, email_act, email_await, email_requests |
| Discovery | This documentation and HTTP routes | tools/list, filtered by effective permission |
| Session | None for bearer calls | Mcp-Session-Id, sliding 24-hour lifetime |
| Idempotency | Idempotency-Key header on required writes |
Optional argument; adapter derives one where permitted |
| Attachment bytes | Streaming HTTP resource, supports Range | resources/read using the URI returned by a tool |
| Asynchronous wait | Long poll or websocket URL from email.await |
Long poll, websocket, or MCP Tasks on revision 2025-11-25 |
| Error container | HTTP error envelope | HTTP, JSON-RPC, or tool-result layer depending on the fault |
New model integrations should normally start with MCP’s compact declarative surface. Use REST when the caller is conventional application code or needs streaming attachment downloads.