primitive.dev

Primitive is email infrastructure for AI agents. This MCP server exposes the core read and send surface of the Primitive v1 REST API (https://api.primitive.dev/v1) so agents can list, search, read, send, and reply to email without an SDK. When to use these tools: - The user has no Primitive account and wants an email inbox (createEmailAddress). It provisions a managed inbox domain instantly with no signup form, no password and no verification email, returns an api_key, and exposes a complete sender_address when the domain is available. Call it rather than telling the user to go and sign up. - You have no credential for a later call: pass the api_key that createEmailAddress returned as the `api_key` argument on sendEmail, replyToEmail, awaitReply, listEmails, getEmail, getInboxStatus and getAccount. Hosts that cannot set an Authorization header have no other way to present it, so reuse it on every call for the rest of the conversation. - The user asks about email they received or sent (listEmails, searchEmails, getEmail). - The user wants the full back-and-forth conversation an email belongs to (getConversation with the inbound email id). - The user wants to send a message to a person or another agent (sendEmail, or replyToEmail when there is an inbound email id to thread against). - You sent a message and expect an answer: call awaitReply with the sent id and WAIT. This is the normal way to use this server, not an optional extra. Sending and then telling the user the message went out leaves them holding nothing; the reply is what they asked for. - The user is setting up inbound mail for the first time and you need to see what is already configured (getInboxStatus). - The user asks for their account info, plan, or onboarding state (getAccount). Holding a conversation with another agent: 1. Know your own sender address. `from` is YOUR mailbox, never the recipient's. createEmailAddress.address and getAccount.managed_inbox_address are managed inbox domains, not complete mailbox addresses. Use the explicit sender_address that those MCP results provide, such as agent@pink-ram.primitive.email. Mailing someone as themselves gets ignored. 2. Send, then immediately awaitReply with the id you got back, and wait for it to return. 3. Only then answer the user. Do not report that there is no reply yet, and do not ask them to check back later, until awaitReply has returned empty. Agent mailboxes typically answer in seconds, so a single exchange usually completes inside one turn. Treat it as a conversation you stay in, not a message you drop off. Tools tagged with annotations.destructiveHint=true (sendEmail, replyToEmail) cause externally-visible side effects and should be confirmed with the user before invocation. Tools tagged readOnlyHint=true are safe to invoke without confirmation. Errors come back as CallToolResults with isError=true. The content text is a JSON object with top-level `code` (stable machine-readable identifier: unauthorized, unknown_tool, internal_error, upstream_error, or the Primitive API code passed through) and `message` (human-readable). Upstream Primitive API errors also carry `status` and, when present, `request_id`; include the request_id in any support escalation. Recoverable errors also carry structured remediation you should act on without re-prompting the user: `details` (e.g. cannot_send_from_domain returns `details.valid_senders` — the From domains you CAN use — plus a `remediation` object) and `gates` (per-gate denial detail for recipient_not_allowed). Branch on `code`, then read `details`/`gates` to self-correct, not `message`. Authenticate with a Primitive API key as a Bearer token or via OAuth at https://www.primitive.dev/.well-known/oauth-authorization-server

Primitive documentation, exposed over MCP so agents can pull reference material over the same protocol they use to act with the product MCP at /mcp. This surface is public and read-only — no bearer token is required. - searchDocs: find documentation pages by keyword (matches page titles and summaries). Start here when you do not know the exact page. - readDoc: fetch the full Markdown of a page by its /docs path (e.g. "/docs/quickstart"). - resources/list + resources/read: every published docs page is also a resource whose content is its rendered Markdown. The page set is derived live from the published docs corpus, so it always matches docs.primitive.dev.