> ## Documentation Index
> Fetch the complete documentation index at: https://nuntly.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Use Nuntly from Claude Code, Cursor and VS Code

> Connect the Nuntly MCP server, SDK and CLI to your coding agent, from a one-line prompt or by hand, and see what an agent can do with them.

An AI agent can send email, and it can also own an inbox: receive each message by webhook, reply in the same thread, and keep a memory per conversation through the [agent inbox and memory API](https://nuntly.com/docs/guides/receiving-agents.md). The MCP server (`@nuntly/sdk-mcp`) exposes all of it as tools for Claude Code, Cursor, VS Code and any client that speaks the Model Context Protocol. The TypeScript SDK (`@nuntly/sdk`) and the CLI (`@nuntly/cli`) cover the same API from code and from a shell.

## Prerequisites

* A Nuntly account. See [account setup](https://nuntly.com/docs/guides/account-setup.md).
* An API key. Pick **Sending only** for an agent that only sends, and **Full access** for an agent that manages domains, inboxes, webhooks or agent memory. See [API keys](https://nuntly.com/docs/guides/api-keys.md).
* Node.js 20 or later. To install it, take the current LTS release from [nodejs.org](https://nodejs.org). The MCP server runs with `npx`, which ships with Node.js.

## Set up from a one-line prompt

Paste one of these lines into your agent, in the project you want to set up. Each points to an install guide written for an agent. The agent checks your environment and installs the package. It asks you to create the API key in the dashboard, sends a test email to your address, and ends with a setup report.

```text Claude Code in a terminal theme={null}
Download https://nuntly.com/claude-code/install.md raw (`curl -fsSL` on macOS and Linux, `curl.exe -fsSL` on Windows), read the whole output, and follow it word for word to connect Nuntly to Claude Code.
```

```text Cursor or VS Code theme={null}
Download https://nuntly.com/cursor/install.md raw (`curl -fsSL` on macOS and Linux, `curl.exe -fsSL` on Windows), read the whole output, and follow it word for word to connect Nuntly to this editor.
```

```text Move a codebase theme={null}
Download https://nuntly.com/integration/install.md raw (`curl -fsSL` on macOS and Linux, `curl.exe -fsSL` on Windows), read the whole output, and follow it word for word to move this codebase to Nuntly.
```

The migration guide finds the existing send calls of Resend, Postmark, Mailgun or SendGrid and replaces them in place with the Nuntly SDK. It lists for you the calls it cannot map (provider templates, raw MIME, some SMTP clients), then runs your build.

Every guide keeps the API key out of the conversation: you paste the key into your editor or terminal, and the agent never prints or commits it. The test email goes from `hello@onboarding.nuntly.com` to the address of the organization owner, so it works before you add a domain.

## Manual quickstart

**1. Create an API key**

In the dashboard, go to **API Keys** and create a key with the **Sending only** permission, and leave **Restrict to domains** empty. Copy it.

**2. Add the MCP server**

Follow the section for your client: [Cursor and VS Code](#cursor-and-vs-code) or [Claude Code](#claude-code).

**3. Send a test email**

Ask your agent: "Send a test email from [hello@onboarding.nuntly.com](mailto:hello@onboarding.nuntly.com) to my address." Use the email address of your Nuntly account (the organization owner), exactly as you signed up. This sender only delivers to that address.

## Cursor and VS Code

Install the server with one click, then add your key:

* [Install in Cursor](https://cursor.com/install-mcp?name=nuntly\&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBudW50bHkvc2RrLW1jcEAyIl0sImVudiI6eyJOVU5UTFlfQVBJX0tFWSI6InlvdXItYXBpLWtleSJ9fQ%3D%3D). After the install, open **Customize** in the sidebar, edit the `nuntly` server, and replace `your-api-key` with your key. Save and close the file, then turn the server off and on with its toggle so that it starts with your key.
* For a VS Code Local session, [install in VS Code](https://insiders.vscode.dev/redirect/mcp/install?name=nuntly\&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22nuntly-api-key%22%2C%22description%22%3A%22Nuntly%20API%20key%22%2C%22password%22%3Atrue%7D%5D\&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40nuntly%2Fsdk-mcp%402%22%5D%2C%22env%22%3A%7B%22NUNTLY_API_KEY%22%3A%22%24%7Binput%3Anuntly-api-key%7D%22%7D%7D). VS Code asks for your key when the server first starts (**MCP: List Servers**, then start `nuntly`) and stores it outside the configuration file.

If a link does not open your editor, add the server by hand.

```json Cursor (~/.cursor/mcp.json, %USERPROFILE%.cursor\mcp.json on Windows) theme={null}
{
  "mcpServers": {
    "nuntly": {
      "command": "npx",
      "args": ["-y", "@nuntly/sdk-mcp@2"],
      "env": {
        "NUNTLY_API_KEY": "your-api-key"
      }
    }
  }
}
```

```json VS Code, Local session (.vscode/mcp.json) theme={null}
{
  "inputs": [
    {
      "type": "promptString",
      "id": "nuntly-api-key",
      "description": "Nuntly API key",
      "password": true
    }
  ],
  "servers": {
    "nuntly": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@nuntly/sdk-mcp@2"],
      "env": {
        "NUNTLY_API_KEY": "${input:nuntly-api-key}"
      }
    }
  }
}
```

```json VS Code, Copilot session (~/.copilot/mcp-config.json) theme={null}
{
  "mcpServers": {
    "nuntly": {
      "command": "npx",
      "args": ["-y", "@nuntly/sdk-mcp@2"],
      "env": {
        "NUNTLY_API_KEY": "your-api-key"
      }
    }
  }
}
```

The Local session file holds no key, so you can commit it and share the server with your team. A Copilot session reads the portable `mcpServers` format, and VS Code does not pass it a server that asks for an input. So in a Copilot session, put the entry in your user file `~/.copilot/mcp-config.json`, outside the repository, and save and close it once your key is in.

## Claude Code

Exit Claude Code if it runs, then run this from your project root, since Claude Code registers the server for the directory you run it in. Paste your key when the cursor waits, and press Enter. In PowerShell, keep `'--'` in quotes so that an npm-installed `claude.ps1` passes it on:

```bash bash or zsh theme={null}
printf 'Nuntly API key: ' && read -rs NUNTLY_API_KEY && claude mcp add --env NUNTLY_API_KEY="$NUNTLY_API_KEY" --transport stdio nuntly -- npx -y @nuntly/sdk-mcp@2; unset NUNTLY_API_KEY
```

```powershell PowerShell theme={null}
$key = Read-Host -AsSecureString 'Nuntly API key'; claude mcp add --env "NUNTLY_API_KEY=$([System.Net.NetworkCredential]::new('', $key).Password)" --transport stdio nuntly '--' npx -y @nuntly/sdk-mcp@2; Remove-Variable key
```

The key never shows on screen (PowerShell shows `*` for each character) and never lands in your shell history. Claude Code stores the server in `~/.claude.json` (`%USERPROFILE%\.claude.json` on Windows), scoped to this project. Start a new Claude Code session, then check the connection:

```bash theme={null}
claude mcp list
```

The `nuntly` line reads `Connected`. To share the server with your team, commit a `.mcp.json` file at the project root. It reads the key from the environment Claude Code starts in, so each person sets their own `NUNTLY_API_KEY`. Claude Code asks each person to approve a project server on first use. When the variable is unset, it passes the literal `${NUNTLY_API_KEY}` text, which makes every call fail with a `401`:

```json .mcp.json theme={null}
{
  "mcpServers": {
    "nuntly": {
      "command": "npx",
      "args": ["-y", "@nuntly/sdk-mcp@2"],
      "env": {
        "NUNTLY_API_KEY": "${NUNTLY_API_KEY}"
      }
    }
  }
}
```

## CLI

The CLI gives an agent the same operations as shell commands, with JSON output and documented exit codes. Install it with npm, Homebrew or the PowerShell installer, then save your key:

```bash npm theme={null}
npm install -g @nuntly/cli
```

```bash Homebrew theme={null}
brew install nuntly/tap/nuntly
```

```powershell PowerShell theme={null}
irm https://raw.githubusercontent.com/nuntly/nuntly-cli/main/scripts/install.ps1 | iex
```

```bash theme={null}
nuntly login
nuntly emails send --from hello@onboarding.nuntly.com --to you@example.com --subject "Hello" --text "Sent from the CLI"
```

`nuntly login` asks for the key without echoing it, then for an API base URL: leave it empty. It saves both to `~/.nuntly/config.json` (`%USERPROFILE%\.nuntly\config.json` on Windows). An agent or a CI job sets the `NUNTLY_API_KEY` environment variable instead, which the CLI reads when no profile is selected. Destructive commands and `broadcasts send` ask for confirmation, and refuse to run without a terminal unless you pass `--yes`. Run `nuntly <command> --help` for every option, and see [CLI](https://nuntly.com/docs/api-reference/cli.md) for the other install methods.

## Walkthrough: an agent inbox

This walkthrough gives an agent its own inbox and lets it answer and remember a conversation through MCP tools. It needs a **Full access** key. Ask your agent each step in plain words, and it calls the tool shown.

| You ask | Tool the agent calls |
| - | - |
| "Create an inbox `support` for agent `support-agent-v1`." | `create-inbox` with `address`, `agentId` and the `domainId` of a verified domain with receiving active and sending enabled. Without `domainId`, the inbox uses the receiving-only subdomain your organization gets at sign-up, and a reply from it fails |
| "List the threads in that inbox." | `list-inbox-threads` |
| "Read the last message and draft a reply." | `list-thread-messages`, then `retrieve-message` and `retrieve-message-content`, which returns download links for the body |
| "Send the reply." | `reply-message`, with `replyAll` set to `true` or `false`, which adds the reply to the same thread |
| "Remember that this customer prefers French." | `upsert-agent-memory` with the `agentId` and the `threadId` |
| "What do you remember about this thread?" | `retrieve-agent-memory` with the `agentId` and the `threadId`. It returns an empty memory when nothing is saved yet |

To run the same loop without a human in it, subscribe a webhook to `message.agent.triggered` and call the API from your handler. [AI agent inboxes](https://nuntly.com/docs/guides/receiving-agents.md) has a complete example.

## Vercel AI SDK

The AI SDK connects to the MCP server through its MCP client and passes the tools to the model. Install `ai`, `@ai-sdk/mcp` and a provider such as `@ai-sdk/anthropic`:

```typescript agent.ts theme={null}
import { anthropic } from '@ai-sdk/anthropic';
import { createMCPClient } from '@ai-sdk/mcp';
import { Experimental_StdioMCPTransport } from '@ai-sdk/mcp/mcp-stdio';
import { generateText, isStepCount } from 'ai';

const apiKey = process.env.NUNTLY_API_KEY;
if (!apiKey) throw new Error('Set NUNTLY_API_KEY before you start the agent.');

const nuntly = await createMCPClient({
  transport: new Experimental_StdioMCPTransport({
    command: 'npx',
    args: ['-y', '@nuntly/sdk-mcp@2'],
    env: { NUNTLY_API_KEY: apiKey },
  }),
});

try {
  const { text } = await generateText({
    model: anthropic('claude-sonnet-5-5'),
    tools: await nuntly.tools(),
    stopWhen: isStepCount(5),
    prompt: 'Send a one-line status email from hello@yourdomain.com to you@example.com.',
  });
  console.log(text);
} finally {
  await nuntly.close();
}
```

The stdio transport runs on Node.js only. The sample uses `ai` 7, where `isStepCount` limits the number of tool-calling steps. See the [AI SDK MCP documentation](https://ai-sdk.dev/docs/ai-sdk-core/mcp-tools) for other transports.

## Troubleshooting

**The server does not appear in your client.** Check the JSON syntax of the configuration file: a trailing comma breaks the whole file. Restart the client, and run `npx -y @nuntly/sdk-mcp@2` in a terminal. It prints `NUNTLY_API_KEY environment variable is required.` or waits silently: both mean the command resolves. Press Ctrl+C to stop it.

**The server does not start in Cursor or VS Code.** In Cursor, open the Output panel and select **MCP Logs**. In VS Code, run **MCP: List Servers**, select `nuntly` and open its output. On native Windows, an error that names `npx` can mean that the editor cannot start `npx` directly: set `"command": "cmd"` and `"args": ["/c", "npx", "-y", "@nuntly/sdk-mcp@2"]`.

**`NUNTLY_API_KEY environment variable is required.` at startup.** The server reads the key from the `env` of its client configuration. Put it there.

**A tool returns `isError: true`.** The result text gives the HTTP status, the error title and the request id. Give the request id to support.

* A `401` titled `Onboarding emails can only be sent to the organization owner` means the recipient is not your account address. Any other `401` means the key is wrong, revoked or mistyped.
* A `403` that names a domain means the key is restricted to other domains: clear **Restrict to domains** on the key.
* A `403` that says the organization is not active means it cannot send: contact support.
* Any other `403` means the key lacks the permission, for example a **Sending only** key on a tool that reads or manages resources.

**A tool rejects an argument.** The server refuses an argument the tool does not declare and sends no request. Use the argument names that `tools/list` returns, for example `scheduledAt`.

**`command not found: npx` (bash) or `The term 'npx' is not recognized` (PowerShell).** Install the current LTS release of Node.js from [nodejs.org](https://nodejs.org).

**Claude Code shows `Failed to connect` for `nuntly`.** The first download can outlast the health check, so wait a few seconds and run `claude mcp list` again. If it still fails on native Windows, run `claude mcp remove nuntly`, then add the server again with `cmd /c npx -y @nuntly/sdk-mcp@2` in place of `npx -y @nuntly/sdk-mcp@2`.

**Claude Code shows your key.** `claude mcp get nuntly` prints the server's environment, key included. Use `claude mcp list` to check the connection.

## What an agent can do, and what stays with you

An agent with a **Full access** key reaches the same operations as the dashboard through the API, the MCP server and the CLI, with the exceptions below. They stay with you because they involve your identity, your money, or access to your organization.

| Area | Your agent can | Stays with you | Why |
| - | - | - | - |
| Emails | Send, send in bulk, schedule, cancel, read the status, events and stats | Nothing | |
| Domains | Add a domain, read its DNS records, check its status, update or delete it | Adding the records at your DNS provider | Your DNS provider needs your login. Verification runs in the background, and the agent polls `retrieve-domain` |
| API keys | Create, list, update and revoke keys | The first key | The agent needs a key to call the API, so you create the first one in the dashboard |
| Webhooks | Create, update and delete endpoints, list and replay events | Nothing | |
| Inboxes and agent memory | Create inboxes and namespaces, read threads and messages, reply, forward, read and write memory | Nothing | |
| Broadcast | Manage templates, contacts, properties, segments and topics, create and send broadcasts | Nothing | |
| Organization | Read the organization | Members, invitations, the organization name | A key that could invite a member would turn a leaked key into a takeover of your organization |
| Billing | Read usage | Plan changes and payment | Payment needs you: card details and strong customer authentication |
| Account | Nothing | Sign-up, sign-in, two-factor authentication, password | They prove who you are |
| Search and logs | List emails page by page | Filtering emails by status or date, API request logs | The API lists emails without filters and has no request log endpoint. Use the dashboard |

## Next steps

> **[AI agent inboxes](https://nuntly.com/docs/guides/receiving-agents.md)**
>
> Receive messages by webhook and keep a memory per thread

> **[API keys](https://nuntly.com/docs/guides/api-keys.md)**
>
> Choose between Sending only and Full access

> **[SDKs](https://nuntly.com/docs/api-reference/sdks.md)**
>
> Install the TypeScript or Java SDK

> **[Webhooks](https://nuntly.com/docs/guides/webhooks.md)**
>
> Get notified of deliveries, bounces and inbound messages


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.