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

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">
    The server resolves the API key using the following priority order. Use whichever method fits your client:

    **1. OAuth connector form (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**

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

    ```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 (any transport)**

    Pass `apiKey` directly in each tool call. This takes the highest runtime priority and overrides any other credential source. Useful for scripted clients or one-off requests.
  </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

| Tool | Credential required |
| :- | :- |
| `send_secure_email` | Paubox Email API key with send access |
| `check_email_status` | Paubox Email API key with read access |
| `validate_credentials` | Any valid Paubox Email API key |
| `get_form` | None (public endpoint) |
| `submit_form` | None (public endpoint) |

A single API key generated from the Paubox Email API [API Keys](https://next.paubox.com/settings/api_keys) page covers all authenticated tools. The `get_form` and `submit_form` tools call public Forms API endpoints and require no credentials.


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