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

# Local MCP setup

> Run the stdio adapter in a separate Python environment.

> [!NOTE]
>
> The examples use the canonical app host. Production API access is currently disabled. Configure the enabled host issued with your key; see [API availability](https://docs.emailx.ai/en/api-reference/introduction.md).

## Prerequisites

Python 3.11 or newer, a stdio-capable MCP host, and an expiring key with `workspaces:read` plus the resource scopes you need. The package is distributed as source from Emailx; it is not published on a public package registry.

## Install the supported adapter

```bash theme={null}
export EMAILX_BASE_URL="https://app.emailx.ai"
python3 -m venv .venv-emailx
. .venv-emailx/bin/activate
python -m pip install "emailx-agent[mcp] @ $EMAILX_BASE_URL/api/emailx-agent.zip"
emailx --version
```

Keep the MCP SDK out of the Flask application's Python environment. The optional extra installs its own pinned SDK dependencies.

## Configure your host

Create the private key file with your secret manager or editor. It must contain only the key, be owned by your user, be a regular non-symlink file, and have mode `0600`. The path is safe to put in the configuration; the key itself is not.

```json theme={null}
{
  "mcpServers": {
    "emailx": {
      "command": "/absolute/path/.venv-emailx/bin/emailx",
      "args": ["mcp", "serve", "--transport", "stdio"],
      "env": {
        "EMAILX_BASE_URL": "https://app.emailx.ai",
        "EMAILX_API_KEY_FILE": "/absolute/private/path/emailx-staging.key"
      }
    }
  }
}
```

This is a generic stdio configuration. Adapt the wrapper to your host and replace the absolute paths. Use exactly one of `EMAILX_API_KEY` or `EMAILX_API_KEY_FILE`. No host or customer is selected by default. HTTPS is required except explicit loopback development.

## Verify the connection

Run `emailx doctor --json`, then `emailx auth status --json` from the configured environment. Restart the MCP host and ask it to list tools, inspect the connection, and list workspaces. Compare the returned environment and intended account before using resource tools.

If the host cannot start the process, check the executable path and `[mcp]` installation. If it returns 401, check expiry, host and key environment. A 403 needs a role/scope review; a 404 can mean the selected client is no longer accessible. See [recovery](https://docs.emailx.ai/en/mcp/recovery.md).


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