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

# Connect your client

> Add the AlpacaRelay MCP server to Claude, ChatGPT, Cursor, VS Code, Codex, and other MCP clients, by signing in or with an API key.

The server is remote, at `https://app.alpacarelay.com/api/mcp` over Streamable HTTP. Every client below connects to that one URL. You sign in through your browser (OAuth) or send an API key:

| | Sign in (OAuth) | API key |
| - | - | - |
| Who can use it | Any member of the workspace | Keys are created by workspace owners |
| Acts as | You, with your own permissions | The owner who created the key |
| Secret in your config | None | The key, in plain text |
| Best for | Chat apps, editors, and CLIs you use yourself | CI, shared machines, clients without sign-in |

Sign in whenever your client supports it. There's no secret to leak from a config file, and it works for members who aren't owners. The setups below use sign-in. [Connect with an API key](#connect-with-an-api-key) covers the alternative.

> [!TIP]
>
> **In more than one workspace?** Add `?org=` with the workspace's ID to the URL in any setup below, such as `https://app.alpacarelay.com/api/mcp?org=3f2a1b4c-…`. See [Choose a workspace](#choose-a-workspace).

## Add the server

Pick your client. Menu names change between app versions, so if a path doesn't match exactly, look for the app's **Connectors** or **MCP servers** settings.

> [tab] Claude
>
> For Claude Desktop and Claude on the web (claude.ai). Both use the same connector, so adding it once makes it available in both.
>
> 1. Open **Customize** → **Connectors** → **+ Add** → **Add custom connector**.
>
> 2. Name it `AlpacaRelay`, paste the server URL, and click **Continue**:
>
>    ```text theme={null}
>    https://app.alpacarelay.com/api/mcp
>    ```
>
> 3. Click **Connect**, sign in to AlpacaRelay, and approve the connection.
>
> 4. In a conversation, open **+** → **Connectors** and turn AlpacaRelay on.
>
> > [!NOTE]
> >
> > On a Claude Team or Enterprise plan, an owner or admin adds the connector first, under **Organization settings** → **Connectors**. Free Claude accounts can add only one custom connector.

> [tab] ChatGPT
>
> **On the web (chatgpt.com):**
>
> 1. Open **Plugins** → **+** → **Add custom MCP server**.
>
> 2. Name it `AlpacaRelay`. Under **Connection**, paste the server URL and choose **OAuth**:
>
>    ```text theme={null}
>    https://app.alpacarelay.com/api/mcp
>    ```
>
> 3. Review ChatGPT's warning about custom servers, confirm, and create the plugin.
>
> 4. Install it, sign in to AlpacaRelay, and approve the connection.
>
> 5. In a new chat, type `@` and choose AlpacaRelay.
>
> **In the ChatGPT desktop app:**
>
> 1. Open **Settings** → **Plugins** → **MCPs** → **Add** → **Add MCP server**. Some versions call this **Settings** → **MCP servers** → **Add server**.
>
> 2. Name it `alpacarelay-email`, choose **Streamable HTTP**, and paste the server URL. Leave the token and header fields empty.
>
>    ```text theme={null}
>    https://app.alpacarelay.com/api/mcp
>    ```
>
> 3. Save, then click **Authenticate** on the server and sign in.
>
> > [!NOTE]
> >
> > Custom MCP servers with full tool access need a ChatGPT Business, Enterprise, or Edu plan, and on Business an admin or owner creates them. On other plans ChatGPT may allow only read-style tools, which leaves most AlpacaRelay tools unusable. If you change plans or AlpacaRelay adds tools, refresh the plugin's tools.

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http --scope user alpacarelay-email \
>   https://app.alpacarelay.com/api/mcp
> ```
>
> `--scope user` makes it available in every project. Leave it out to add it to the current project only.
>
> Then sign in with `claude mcp login alpacarelay-email`, or run `/mcp` in a session, choose `alpacarelay-email`, and authenticate.

> [tab] Cursor
>
> [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=alpacarelay-email\&config=eyJ1cmwiOiJodHRwczovL2FwcC5hbHBhY2FyZWxheS5jb20vYXBpL21jcCJ9) with one click, or add it to `~/.cursor/mcp.json` for every project, or `.cursor/mcp.json` for one:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "alpacarelay-email": {
>       "url": "https://app.alpacarelay.com/api/mcp"
>     }
>   }
> }
> ```
>
> Then open Cursor's MCP settings (**Customize** → **MCP**, or **Tools & MCP** in older versions), choose `alpacarelay-email`, and sign in.

> [tab] VS Code
>
> Run **MCP: Add Server** from the Command Palette and choose **HTTP**, or add the server from a terminal:
>
> ```bash theme={null}
> code --add-mcp '{"name":"alpacarelay-email","type":"http","url":"https://app.alpacarelay.com/api/mcp"}'
> ```
>
> Or add it to `.vscode/mcp.json` for one workspace (use **MCP: Open User Configuration** for all of them):
>
> ```json theme={null}
> {
>   "servers": {
>     "alpacarelay-email": {
>       "type": "http",
>       "url": "https://app.alpacarelay.com/api/mcp"
>     }
>   }
> }
> ```
>
> Click **Start** above the server's entry and sign in when the browser opens. Then in Chat, switch to **Agent**, open **Configure Tools**, and turn on the AlpacaRelay tools.
>
> > [!NOTE]
> >
> > MCP in VS Code runs through GitHub Copilot. On Copilot Business or Enterprise, an admin has to allow MCP servers.

> [tab] Codex
>
> For the Codex CLI, IDE extension, and desktop app. On the same machine they share one config.
>
> ```bash theme={null}
> codex mcp add alpacarelay-email --url https://app.alpacarelay.com/api/mcp
> codex mcp login alpacarelay-email
> ```
>
> Or add it to `~/.codex/config.toml` yourself, then run `codex mcp login alpacarelay-email`:
>
> ```toml theme={null}
> [mcp_servers.alpacarelay-email]
> url = "https://app.alpacarelay.com/api/mcp"
> ```
>
> Check it with `codex mcp list`, or `/mcp` in a session.
>
> > [!NOTE]
> >
> > On Windows with WSL, the Windows app and WSL can have separate home folders and so separate configs. ChatGPT on the web doesn't read this file. See the ChatGPT tab.

> [tab] Gemini CLI
>
> Add it to `~/.gemini/settings.json`:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "alpacarelay-email": {
>       "httpUrl": "https://app.alpacarelay.com/api/mcp"
>     }
>   }
> }
> ```
>
> Start `gemini` and run `/mcp auth alpacarelay-email` to sign in. `/mcp` lists the server and its tools.

> [tab] OpenCode
>
> Add it to `~/.config/opencode/opencode.json`:
>
> ```json theme={null}
> {
>   "mcp": {
>     "alpacarelay-email": {
>       "type": "remote",
>       "url": "https://app.alpacarelay.com/api/mcp",
>       "enabled": true
>     }
>   }
> }
> ```
>
> Sign in with `opencode mcp auth alpacarelay-email`, or when OpenCode first asks. Check it with `opencode mcp list`.

> [tab] Cline
>
> Click the **MCP Servers** icon and open **Remote Servers**. Enter the name `alpacarelay-email`, paste the server URL, choose **Streamable HTTP**, and click **Add Server**. Then click **Authenticate** on its row.
>
> ```text theme={null}
> https://app.alpacarelay.com/api/mcp
> ```
>
> Or open **MCP Servers** → **Configure** → **Configure MCP Servers** and add it to `cline_mcp_settings.json`:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "alpacarelay-email": {
>       "type": "streamableHttp",
>       "url": "https://app.alpacarelay.com/api/mcp",
>       "disabled": false
>     }
>   }
> }
> ```
>
> > [!NOTE]
> >
> > Keep `"type": "streamableHttp"`. Without it Cline falls back to the older SSE transport.

> [tab] Goose
>
> In the terminal, run `goose configure`, choose **Add Extension** → **Remote Extension (Streamable HTTP)**, name it `alpacarelay-email`, and paste the server URL:
>
> ```text theme={null}
> https://app.alpacarelay.com/api/mcp
> ```
>
> In Goose Desktop, open **Extensions** → **Add custom extension**, choose **Streamable HTTP**, and enter the same URL.
>
> Sign in when Goose asks.

> [tab] Grok
>
> **On the web (grok.com):** open [grok.com/connectors](https://grok.com/connectors) → **New Connector** → **Custom**, paste the server URL, then sign in and approve. On a Grok Business or Enterprise plan, a team admin adds the connector first.
>
> ```text theme={null}
> https://app.alpacarelay.com/api/mcp
> ```
>
> **Grok Build (CLI):**
>
> ```bash theme={null}
> grok mcp add --transport http alpacarelay-email https://app.alpacarelay.com/api/mcp
> ```
>
> If it asks you to sign in, open `/mcps`, choose `alpacarelay-email`, and press `i`. Check it with `grok mcp doctor alpacarelay-email`.

> [tab] Devin Desktop
>
> Devin Desktop replaces Windsurf. Add the server to `~/.config/devin/mcp_config.json` on macOS and Linux, or `%APPDATA%\devin\mcp_config.json` on Windows:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "alpacarelay-email": {
>       "url": "https://app.alpacarelay.com/api/mcp"
>     }
>   }
> }
> ```
>
> Sign in with `devin mcp login alpacarelay-email`, or when Devin first uses the server. Check it with `devin mcp list`. Your organization's policy may limit which servers you can add.

> [tab] Manus
>
> Connect Manus with an [API key](#connect-with-an-api-key) rather than signing in.
>
> 1. Open **Connectors** → **Create** → **Add MCP by URL**. Older versions use **Settings** → **Integrations** → **Custom MCP Servers** → **Add Server**.
>
> 2. Name it `AlpacaRelay` and paste the server URL:
>
>    ```text theme={null}
>    https://app.alpacarelay.com/api/mcp
>    ```
>
> 3. Paste your key into the bearer-token field, or add a header `Authorization` with the value `Bearer ar_live_…`.
>
> 4. Save and test the connection.

> [tab] Other clients
>
> Any client that supports remote MCP servers over Streamable HTTP and OAuth can connect. Most JSON configs look like this:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "alpacarelay-email": {
>       "type": "http",
>       "url": "https://app.alpacarelay.com/api/mcp"
>     }
>   }
> }
> ```
>
> The top-level key and the `type` value vary by client. VS Code uses `servers`, OpenCode uses `mcp` with `"type": "remote"`, Cline needs `"type": "streamableHttp"`, and Gemini CLI uses `httpUrl` in place of `url`. Clients that only run local (stdio) servers can connect through [`mcp-remote`](#clients-that-only-run-local-servers).

**Restart your client** after editing a config file. Most clients read MCP config only at startup.

## Sign in

The first time the client connects, it opens a browser window where you sign in to AlpacaRelay and approve the connection.

> [!WARNING]
>
> **Read the approval page before you click Allow.** It names the client asking for access and the host your sign-in will be sent to. For a chat app such as Claude or ChatGPT, that's the app's own website. For an editor or command-line tool, it's usually `localhost` on your own machine. If you didn't just start a connection, or you don't recognise the host, deny it.

### Choose a workspace

A sign-in identifies **you**, not a workspace, so the URL has to say which workspace to use. Add `?org=` with the workspace's ID:

```text theme={null}
https://app.alpacarelay.com/api/mcp?org=3f2a1b4c-5d6e-4f70-8a91-b2c3d4e5f607
```

You don't need to look the ID up. Connect without it and make any request. If you belong to more than one workspace, the first tool call fails with a list of your workspaces, each with its ready-made URL. Copy the one you want into your client and reconnect. If you belong to one workspace, you never need `?org=`.

To use two workspaces side by side, add the server twice under different names, each with its own `?org=`.

### How long a sign-in lasts

Your client refreshes access on its own every hour. The refresh lasts seven days, so after a week without connecting you'll be asked to sign in again.

> [!NOTE]
>
> There's no screen yet that lists or revokes the clients you've approved. An approved client keeps access until its sign-in expires. If you lose a device with an approved client, tell support.

## Connect with an API key

Use a key for CI and other unattended setups, for shared machines, and for clients that can't sign in. Create one under **Settings** → **API keys** and copy it, because it's shown only once. Keys are **owner-only**. See [Authentication](https://docs.alpacarelay.com/developers/authentication.md).

A key belongs to one workspace, so it never needs `?org=`. Send it as an `Authorization` header. Replace `ar_live_…` in each example with your key.

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http alpacarelay-email \
>   https://app.alpacarelay.com/api/mcp \
>   --header "Authorization: Bearer ar_live_…"
> ```

> [tab] VS Code
>
> VS Code can ask for the key once and store it securely, so it never sits in `mcp.json`:
>
> ```json theme={null}
> {
>   "inputs": [
>     {
>       "type": "promptString",
>       "id": "alpacarelay-key",
>       "description": "AlpacaRelay API key",
>       "password": true
>     }
>   ],
>   "servers": {
>     "alpacarelay-email": {
>       "type": "http",
>       "url": "https://app.alpacarelay.com/api/mcp",
>       "headers": { "Authorization": "Bearer ${input:alpacarelay-key}" }
>     }
>   }
> }
> ```

> [tab] Codex
>
> Codex reads the key from an environment variable, so it never sits in `config.toml`:
>
> ```toml theme={null}
> [mcp_servers.alpacarelay-email]
> url = "https://app.alpacarelay.com/api/mcp"
> bearer_token_env_var = "ALPACARELAY_API_KEY"
> ```
>
> Then set `ALPACARELAY_API_KEY` in the environment Codex runs in.

> [tab] Cursor, Cline, and others
>
> Add a `headers` entry to the server's config:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "alpacarelay-email": {
>       "url": "https://app.alpacarelay.com/api/mcp",
>       "headers": { "Authorization": "Bearer ar_live_…" }
>     }
>   }
> }
> ```
>
> Keep the client's own `type` value, such as `"streamableHttp"` for Cline.

### Clients that only run local servers

Some clients, including older Claude Desktop versions, can only start local (stdio) servers. Bridge them with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), which needs Node.js so that `npx` is available:

```json theme={null}
{
  "mcpServers": {
    "alpacarelay-email": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.alpacarelay.com/api/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": { "AUTH_HEADER": "Bearer ar_live_…" }
    }
  }
}
```

Leave out `--header` and `env` to sign in instead: `mcp-remote` opens the browser sign-in for you.

### Keep your key out of the repo

> [!WARNING]
>
> A config file with a key in it holds that key in plain text, and the key reaches your whole workspace. Project files such as `.vscode/mcp.json`, `.cursor/mcp.json`, and `.mcp.json` are easy to commit by accident. Add them to `.gitignore` before you paste a key in, or use the VS Code and Codex setups above, which keep the key out of the file. Signing in avoids the problem entirely.

A key in a pushed commit is a leaked key, even if you delete it in the next commit. If that happens, delete the key in **Settings** → **API keys** and create a new one. Deleting a key takes effect immediately.

## Check it worked

Your client should list `alpacarelay-email` with its tools. In chat apps, check that AlpacaRelay is turned on for the conversation.

Then ask for something free and read-only, such as *"list my AlpacaRelay brands"*. Generating or editing an email costs a credit, so it isn't a good first test. Head to [Tools](https://docs.alpacarelay.com/developers/mcp/tools.md) for what else to ask.

## Troubleshooting

> [accordion] The server doesn't appear at all
>
> Restart the client, because most read MCP config only at startup. If it still isn't there, check that you edited the file your client reads, and that the JSON is valid. Cursor's `~/.cursor/mcp.json` applies to every project, while `.cursor/mcp.json` and VS Code's `.vscode/mcp.json` apply to one.

> [accordion] There's no option to add a custom connector or MCP server
>
> Your plan or your organization's settings may not allow it. In ChatGPT, Claude, Grok, and GitHub Copilot, team and enterprise plans usually need an admin to add or allow the server first.

> [accordion] The server is listed but needs authentication
>
> Adding a server only saves its config. Sign in from the client's MCP settings or with its login command, such as `claude mcp login alpacarelay-email` or `codex mcp login alpacarelay-email`. If the client can't sign in, connect with an API key instead.

> [accordion] A tool call says the connection is ambiguous
>
> You belong to more than one workspace and the URL doesn't say which one to use. The message lists a URL for each workspace. Copy one into your client and reconnect.

> [accordion] "You do not have access to that organization"
>
> The `?org=` in your URL names a workspace you're not a member of, or one that doesn't exist. Remove `?org=` to get the list of workspaces you can use.

> [accordion] Every call fails on authentication (API key)
>
> Check the header is exactly `Authorization: Bearer ar_live_…`: the word `Bearer`, a space, then the key. Then confirm the key still exists under **Settings** → **API keys**. A key stops working immediately when it's deleted, and also when the owner who created it leaves the workspace.

> [accordion] mcp-remote won't start
>
> `npx` has to be on the PATH your desktop app sees, which isn't always the PATH in your terminal. Install Node.js system-wide, or put the full path to `npx` in `command`.

> [accordion] New tools don't show up
>
> Some clients cache the tool list. Restart the client, or refresh the server's tools in its MCP settings. In ChatGPT, refresh the plugin's tools; on a Business plan, an admin may need to publish the update.

> [accordion] It connected before and stopped
>
> With a key, the most common cause is a key that was deleted or rotated, or an owner who left the workspace. Create a new key and update the config. With sign-in, sign in again from your client.


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