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

> Connect the Nuntly MCP server to the Codex CLI, keep the API key in your user config or your environment, and send a test email from your agent.

The Nuntly MCP server (`@nuntly/sdk-mcp`) gives Codex 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.

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

Run this in a terminal. Paste your key when the cursor waits, and press Enter:

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

The key never shows on screen and never lands in your shell history. Codex stores the server in `~/.codex/config.toml`, outside your repository, and starts it in every Codex session. Check the configuration:

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

The `nuntly` line shows `NUNTLY_API_KEY=*****` and the status `enabled`. In a Codex session, `/mcp` lists the tools the server exposes.

## Read the key from your environment

To keep the key out of `config.toml`, for example on a shared machine or in CI, add the server by hand and let Codex pass the variable through. Codex gives an MCP server only a short list of variables from your environment, so `env_vars` must name the key:

```toml ~/.codex/config.toml theme={null}
[mcp_servers.nuntly]
command = "npx"
args = ["-y", "@nuntly/sdk-mcp@2"]
env_vars = ["NUNTLY_API_KEY"]
startup_timeout_sec = 60
```

Set `NUNTLY_API_KEY` in the shell that starts Codex. `startup_timeout_sec` leaves time for the first `npx` download.

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

**The server times out at the start of a session.** The first `npx` download can outlast the startup timeout. Add `startup_timeout_sec = 60` to the `[mcp_servers.nuntly]` table and start a new session.

**`NUNTLY_API_KEY environment variable is required.`** With `env_vars`, the variable is missing from the shell that started Codex, or `env_vars` does not name it. Codex does not pass other variables of your environment to the server.

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.