Connect an AI agent to NevarMail

An AI agent can work in your NevarMail account through NevarMail's MCP server: a Model Context Protocol endpoint that exposes your domains, senders, templates, lists, use cases, suppressions and analytics as tools. The agent sees only the tools your credential's scopes allow, and every tool calls the same code as the matching REST endpoint.

What is the NevarMail MCP server?

It is one HTTPS endpoint that any MCP client (Claude, Cursor, your own agent framework) can connect to:

POST https://app.nevarmail.com/api/mcp

• Stateless streamable HTTP. Each request is a JSON-RPC call; there are no sessions to keep alive. GET opens a keepalive stream for clients that expect one, and DELETE answers 405.
• Same rules as the API. A tool call runs the same validation, scope, test-mode and suppression checks as the REST endpoint it mirrors, and returns the same { "data": ... } shape.
• Read-only until you say otherwise. Give the credential only read scopes and the agent cannot change anything.

How do I give an agent access?

There are two ways. Pick one per agent.

Option 1: create an MCP key

1. Open Settings → API Keys and create a key.
2. Set the key type to MCP. API-type keys are refused on the MCP endpoint (403 KEY_TYPE_MISMATCH), and MCP keys are refused on /api/v1/*.
3. Choose Test while you are trying things out. A test key sends only in test mode, whatever the project's mode is.
4. Pick the scopes the agent needs. The table below says which scope unlocks each tool.
5. Copy the key once. It starts with nvm_mcp_live_ or nvm_mcp_test_, and NevarMail never shows it again.

Give the key to your MCP client as a bearer token:

Authorization: Bearer <your MCP key>

Option 2: connect through OAuth

Open Settings → Connected Apps, find the Connect an AI agent card, and copy the discovery URL. Give it to your assistant as the server URL. A connection made this way reaches every project you can open; there is no per-project connection. The agent registers itself, sends you to NevarMail's consent screen, and receives a token limited to the scopes you approve and your role allows. Authenticate API requests explains the consent screen and how a role change narrows the grant.

One OAuth token works on both the MCP endpoint and the REST API. OAuth connections have no test-mode variant: sends follow the send mode of the organization, project and use case the agent sends from.

The Connected Apps page lists every active connection with its scopes and when it was last used. An organization administrator can Disconnect a connection, which revokes it for everyone in the organization who used it.

What should the agent call first?

whoami. It needs only org:read and tells the agent which organization and environment it is in, how it authenticated, whether the credential is a test key, which scopes it holds, and the organization's default send mode for new projects. That default is not the mode a send uses: each send resolves its use case's mode, else its project's, floored to test when the credential is a test key. The only way to rule out live mail is a Test key (Test mode and safe send).

{
  "organization": { "id": "...", "name": "Example Co" },
  "environment": "production",
  "app_url": "https://app.nevarmail.com",
  "auth": {
    "method": "api_key",
    "key_type": "mcp",
    "credential_is_test": true,
    "scopes": ["org:read", "domains:read", "templates:read"]
  },
  "default_send_mode_for_new_projects": "test"
}

Which tools does the agent get?

The MCP server only lists the tools your credential's scopes and your role allow, so an agent with a read-only key never sees create_template. Each tool mirrors one REST endpoint; parameters and responses are documented once, in the API Reference.

Find your footing

Set up a sending domain

See Connect your sending domain for the records the agent will ask you to publish.

Manage senders and templates

render_template returns the subject, HTML and text for a set of variables without sending anything, which is the safe way for an agent to preview mail. Background: Senders and Templates.

Work with lists and contacts

There is no tool for adding contacts; use the REST API or an import for that, as described in Sync contacts and lists from your own system.

Organize sending by use case

Archiving deletes nothing; restore_use_case undoes it. A project's default use case cannot be archived. What a use case is: Your first use case.

Send and measure

send_email_to_list is the only sending tool: it runs the same list sync, suppression and test-mode checks as the REST endpoint, and a test key sends in test mode. There is no single-recipient send tool; for that, call POST /api/v1/email/send with an API key (Send email).

Honor opt-outs

No tool removes a suppression. Removal is dashboard-only and asks for a written reason, as described in Bounces and suppressions.

What happens when a call is refused?

A refused call comes back as a tool error whose text starts with a code, so the agent can act on it:

Every other code is the same as the REST API's, for example NOT_FOUND and RATE_LIMITED; see Error codes. An MCP key has the same per-key rate limit as an API key; an OAuth connection counts against the connecting user's limit instead (Rate limits). List tools page like the REST API: page starts at 1 and perPage is 1 to 100, 25 by default.