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

# MCP Server authentication

> Get a Paubox API key and pass it to the Paubox MCP Server with the OAuth connector, request headers, environment variables, or per-call tool parameters on HTTP.

The Paubox MCP Server authenticates against the Paubox Email API on your behalf. You provide your API key once when configuring the server; it is never sent to the AI model.

<Steps>
  <Step title="Sign up for a Paubox account">
    If you don't have one, [sign up for Paubox Email API](https://www.paubox.com/pricing/paubox-email-api). Free tier includes up to 300 emails per month.
  </Step>

  <Step title="Add and verify your domain">
    Go to [Paubox Email API > Domains](https://next.paubox.com/settings/domains) and add the domain you will send from. Complete domain verification before generating an API key; unverified domains cannot send email.
  </Step>

  <Step title="Generate an API key">
    From [Paubox Email API > API Keys](https://next.paubox.com/settings/api_keys), press **Add API Key**. Give the key a description and save it immediately; it is displayed only once.
  </Step>

  <Step title="Pass your API key to the MCP server">
    How you pass the key depends on the transport. Over HTTP, every request must carry a credential, either an OAuth Bearer token or the `x-paubox-api-key` header; requests with neither are rejected. If both are sent, the header wins. Over stdio, the key comes only from the `PAUBOX_API_KEY` environment variable.

    **1. OAuth connector form (HTTP, recommended for Claude.ai and Claude Desktop)**

    Add `https://mcp.paubox.com` as a connector. The client presents a **Configure Paubox** form automatically. Enter your API key once; the client stores a short-lived encrypted Bearer token and sends it on every subsequent request.

    **2. Custom request headers (HTTP)**

    Some MCP clients let you set custom headers on the connector. Pass:

    ```
    x-paubox-api-key: your_api_key
    ```

    **3. Environment variables (stdio / Claude Code)**

    The stdio server exits at startup if `PAUBOX_API_KEY` is missing or shorter than 10 characters.

    ```bash theme={null}
    export PAUBOX_API_KEY=your_api_key
    ```

    Claude Code / stdio config:

    ```json theme={null}
    {
      "mcpServers": {
        "paubox": {
          "command": "npx",
          "args": ["-y", "@paubox/mcp@latest"],
          "env": {
            "PAUBOX_API_KEY": "your_api_key"
          }
        }
      }
    }
    ```

    **4. Per-call tool parameters (HTTP only)**

    Over HTTP, every tool except `submit_form` accepts an optional `apiKey` parameter. When passed, it overrides the key from the header or OAuth token for that call. The request still needs its own header or Bearer credential to reach the server. The stdio server does not accept an `apiKey` parameter.
  </Step>
</Steps>

<Note>
  Never commit API keys to source control. Use environment variables or a secrets manager to inject credentials at runtime.
</Note>

## Required permissions

| Tools | Credential required |
| :- | :- |
| Email, scheduling, receiving, and webhook tools, plus `validate_credentials` | Paubox Email API key |
| Email Marketing tools | The same Paubox Email API key, on an account with Email Marketing provisioned |
| Forms management tools (`list_forms`, `create_form`, `update_form`, `archive_form`, `unarchive_form`, `copy_form`, `get_form_stats`, `list_form_submissions`, `export_submissions_csv`, `export_submission_pdf`) | API key with the `forms` scope |
| `get_form` | None for active forms. An API key with the `forms` scope also returns inactive and archived forms |
| `submit_form` | None (public endpoint) |

See [MCP tools](/mcp-server/tools) for the tools in each area. `get_form` and `submit_form` call public Forms API endpoints, but the server connection itself still needs a credential: the HTTP transport rejects requests without a header or Bearer token, and the stdio server does not start without `PAUBOX_API_KEY`.


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