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

> Connect the Nuntly MCP server to Claude Code for one project, share it with your team through .mcp.json, and send a test email from your agent.

The Nuntly MCP server (`@nuntly/sdk-mcp`) gives Claude Code tools to send email, manage domains and webhooks, and read and reply to inbound messages. Check the [prerequisites](https://nuntly.com/docs/guides/ai-agents.md#prerequisites) first: an API key and Node.js 20 or later.

## Set up from a one-line prompt

Paste this line into Claude Code, in the project you want to set up. The agent follows an install guide written for it, asks you to create the API key, sends a test email to your address, and ends with a setup report.

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

To set it up yourself, follow the steps below.

## 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. Pick **Full access** instead for an agent that manages domains, inboxes, webhooks or agent memory. See [API keys](https://nuntly.com/docs/guides/api-keys.md).

## Add the MCP server

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 K && \
  claude mcp add nuntly -e NUNTLY_API_KEY="$K" \
  -- npx -y @nuntly/sdk-mcp@2; unset K
```

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

## 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}"
      }
    }
  }
}
```

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

## Troubleshooting

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

For errors shared by every client, such as a tool that returns `isError: true`, see [Troubleshooting](https://nuntly.com/docs/guides/ai-agents-troubleshooting.md).

## Next steps

> [card] [AI agent inboxes](https://nuntly.com/docs/guides/receiving-agents.md)
>
> Give the agent its own inbox and a memory per thread

> [card] [What an agent can do](https://nuntly.com/docs/guides/ai-agents.md#what-an-agent-can-do-and-what-stays-with-you)
>
> See which operations stay with you


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