# MCP server for AI assistants

> Let Claude, Cursor, VS Code and other AI assistants send email and look up delivery status through Vaartix, with the hosted MCP server or the local vaartix-mcp package, and search these docs with the docs MCP server.

Source: https://vaartix.com/docs/guides/mcp/

Vaartix works with AI assistants such as Claude, Cursor and VS Code through the [Model Context Protocol](https://modelcontextprotocol.io) (MCP). They can send email and look up delivery status, emails and domains for you. There are two ways to connect, with the same tools:

|  | Hosted (sign in) | Local (npx) |
| --- | --- | --- |
| Server | `https://mcp.vaartix.com` | `npx -y vaartix-mcp` on your computer |
| Sign-in | Your Vaartix login (OAuth): pick the team and permissions | An API key in your config |
| Install | Nothing | Node.js 20 or later |
| Disconnect | Settings → Connected apps | Revoke the API key |
| Works in | Claude (web, desktop, mobile), Claude Code, Cursor, VS Code and other remote MCP clients | Clients that run local (stdio) servers |

## Hosted (sign in)

Add `https://mcp.vaartix.com` to your AI app and sign in with your Vaartix login. Step-by-step for each app: [Connect Claude, Cursor or VS Code](https://vaartix.com/docs/guides/mcp-hosted/).

Before connecting an app, read [Using Vaartix with AI agents safely](https://vaartix.com/docs/guides/mcp-safety/): what an app can and can’t do, the safe defaults, approvals, and how to see and stop what it does.

## Local (npx)

`vaartix-mcp` runs on your own computer and calls the Vaartix API with an API key. It’s on npm as [vaartix-mcp](https://www.npmjs.com/package/vaartix-mcp) and the source is on GitHub at [vaartix-mail/vaartix-mcp](https://github.com/vaartix-mail/vaartix-mcp). It needs Node.js 20 or later.

### What it can do

| Tool | What it does | API key |
| --- | --- | --- |
| `send_email` | Send one email: HTML and/or text, cc, bcc, reply-to, tags, scheduled sending and an idempotency key | Send-only or full access |
| `send_batch` | Send up to 20 emails in one call | Send-only or full access |
| `get_email` | One email with its status and event timeline; its body only when asked for, and only if the key may read content | Full access |
| `list_emails` | Recent emails, filtered by status, search text or number of days | Full access |
| `cancel_email` | Cancel a scheduled email | Full access |
| `list_domains` | Your sending domains, with verification status and DNS records | Full access |
| `get_domain` | One domain: whether it’s verified, and the DNS records it needs | Full access |

`send_email` and `send_batch` deliver real email. Most AI tools ask you to approve each tool call before it runs: check the recipients and the content before you approve. To try it out, send to a [test address](https://vaartix.com/docs/sending/test-mode/) such as `delivered@test.vaartix.com`. Each email can have at most 50 recipients, and no attachments or custom headers.

### Create an API key

In the [dashboard](https://app.vaartix.com), open **API keys** and create a key for the assistant. When asked **Is this key for an AI agent or MCP server?**, choose **Yes, an AI agent**. The key then starts with safe limits:

-   it can’t read email content (bodies and headers);
-   it can only send to [test addresses](https://vaartix.com/docs/sending/test-mode/);
-   at most 20 emails an hour and 50 a day.

It shows as **AI agent key** in the list. When you’re happy with what the assistant does, an owner or admin can change the limits with **Limits** next to the key, for example to allow your own address or domain. Widening a limit asks for a confirmation code.

For sending only, create a **send-only** key limited to your domain. Use a **full-access** key only if you also want the assistant to read your email logs: `get_email`, `list_emails` and `cancel_email` need one. See [API keys](https://vaartix.com/docs/concepts/api-keys/).

### Set it up

**Claude Desktop**

Open **Settings** → **Developer** → **Edit Config**, and add the server to the config file:

claude\_desktop\_config.json

```json
{
  "mcpServers": {
    "vaartix": {
      "command": "npx",
      "args": ["-y", "vaartix-mcp"],
      "env": { "VAARTIX_API_KEY": "vx_your_api_key" }
    }
  }
}
```

Then restart Claude Desktop.

### Configuration

| Variable | Required | Default |
| --- | --- | --- |
| `VAARTIX_API_KEY` | Yes |  |
| `VAARTIX_BASE_URL` | No | `https://api.vaartix.com` |

### Things to ask

-   “Send a test email to [delivered@test.vaartix.com](mailto:delivered@test.vaartix.com)”
-   “How many emails bounced today?”
-   “Did the order confirmation to [ravi@example.com](mailto:ravi@example.com) get delivered?”
-   “Show me emails that bounced in the last 7 days”
-   “Cancel my scheduled email em\_…”

Reading questions need a full-access key (or, on the hosted server, the read permission); with a send-only key the assistant can only send.

### Keep the key safe

-   The key lives only in your local config. Don’t paste it into a chat with the assistant.
-   Keep the config out of shared or committed files: anyone who can read it can send email as you.
-   Create it as an **AI agent key**, and widen its limits only as far as you need. More in [Using Vaartix with AI agents safely](https://vaartix.com/docs/guides/mcp-safety/#ai-agent-api-keys-for-the-local-server).
-   Prefer a send-only key limited to one domain. It can send, but it can’t read your emails, change domains or manage keys.
-   If a key leaks, revoke it in the dashboard under **API keys** and create a new one.

## Docs server

`https://vaartix.com/docs/mcp` is a second MCP server, for these docs: your assistant can search them (`search_docs`) and read any page as markdown (`get_page`). It’s read-only, needs no sign-in and can’t see anything in your Vaartix account. Add it like the hosted server, for example in Claude Code:

```sh
claude mcp add --transport http vaartix-docs https://vaartix.com/docs/mcp
```

Both servers are listed in [vaartix.com/.well-known/ai-catalog.json](https://vaartix.com/.well-known/ai-catalog.json), each with a Server Card ([docs server](https://vaartix.com/docs/mcp/server-card), [hosted server](https://mcp.vaartix.com/server-card)), for tools that discover MCP servers by domain.

Building your own integration instead? Use the [Node.js](https://vaartix.com/docs/sdks/node/), [Python](https://vaartix.com/docs/sdks/python/) or [PHP](https://vaartix.com/docs/sdks/php/) SDK, or the [REST API](https://vaartix.com/docs/api/).