Use Nuntly from Claude Code, Cursor and VS Code

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. 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.
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.
Node.js 20 or later. To install it, take the current LTS release from 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.

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.

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.

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

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.

Add the MCP server

Follow the section for your client: Cursor and VS Code or Claude Code.

Send a test email

Ask your agent: “Send a test email from 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. 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. 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.

{
  "mcpServers": {
    "nuntly": {
      "command": "npx",
      "args": ["-y", "@nuntly/sdk-mcp@2"],
      "env": {
        "NUNTLY_API_KEY": "your-api-key"
      }
    }
  }
}

{
  "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}"
      }
    }
  }
}

{
  "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:

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

$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:

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:

.mcp.json

{
  "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:

npm install -g @nuntly/cli

brew install nuntly/tap/nuntly

irm https://raw.githubusercontent.com/nuntly/nuntly-cli/main/scripts/install.ps1 | iex

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 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 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:

agent.ts

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 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. 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

Receive messages by webhook and keep a memory per thread

API keys

Choose between Sending only and Full access

SDKs

Install the TypeScript or Java SDK

Webhooks

Get notified of deliveries, bounces and inbound messages

Getting started

AI agents

Sending

Receiving

Broadcast

Configuration

Observability

Webhooks

Best practices

Libraries & tools

Frameworks

Use Nuntly from Claude Code, Cursor and VS Code

Prerequisites

Set up from a one-line prompt

Manual quickstart

Cursor and VS Code

Claude Code

CLI

Walkthrough: an agent inbox

Vercel AI SDK

Troubleshooting

What an agent can do, and what stays with you

Next steps

AI agent inboxes

API keys

SDKs

Webhooks

​Prerequisites

​Set up from a one-line prompt

​Manual quickstart

​Cursor and VS Code

​Claude Code

​CLI

​Walkthrough: an agent inbox

​Vercel AI SDK

​Troubleshooting

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

​Next steps

AI agent inboxes

API keys

SDKs

Webhooks

Prerequisites

Set up from a one-line prompt

Manual quickstart

Cursor and VS Code

Claude Code

CLI

Walkthrough: an agent inbox

Vercel AI SDK

Troubleshooting

What an agent can do, and what stays with you

Next steps