Connect your client

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 covers the alternative.

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.

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.

For Claude Desktop and Claude on the web (claude.ai). Both use the same connector, so adding it once makes it available in both.

Open Customize → Connectors → + Add → Add custom connector.
Name it AlpacaRelay, paste the server URL, and click Continue:
https://app.alpacarelay.com/api/mcp
Click Connect, sign in to AlpacaRelay, and approve the connection.
In a conversation, open + → Connectors and turn AlpacaRelay on.

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.

On the web (chatgpt.com):

Open Plugins → + → Add custom MCP server.
Name it AlpacaRelay. Under Connection, paste the server URL and choose OAuth:
https://app.alpacarelay.com/api/mcp
Review ChatGPT’s warning about custom servers, confirm, and create the plugin.
Install it, sign in to AlpacaRelay, and approve the connection.
In a new chat, type @ and choose AlpacaRelay.

In the ChatGPT desktop app:

Open Settings → Plugins → MCPs → Add → Add MCP server. Some versions call this Settings → MCP servers → Add server.
Name it alpacarelay-email, choose Streamable HTTP, and paste the server URL. Leave the token and header fields empty.
https://app.alpacarelay.com/api/mcp
Save, then click Authenticate on the server and sign in.

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.

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.

Add to Cursor with one click, or add it to ~/.cursor/mcp.json for every project, or .cursor/mcp.json for one:

{
  "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.

Run MCP: Add Server from the Command Palette and choose HTTP, or add the server from a terminal:

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

{
  "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.

MCP in VS Code runs through GitHub Copilot. On Copilot Business or Enterprise, an admin has to allow MCP servers.

For the Codex CLI, IDE extension, and desktop app. On the same machine they share one config.

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:

[mcp_servers.alpacarelay-email]
url = "https://app.alpacarelay.com/api/mcp"

Check it with codex mcp list, or /mcp in a session.

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.

Add it to ~/.gemini/settings.json:

{
  "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.

Add it to ~/.config/opencode/opencode.json:

{
  "mcp": {
    "alpacarelay-email": {
      "type": "remote",
      "url": "https://app.alpacarelay.com/api/mcp",
      "enabled": true
    }
  }
}

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.

https://app.alpacarelay.com/api/mcp

Or open MCP Servers → Configure → Configure MCP Servers and add it to cline_mcp_settings.json:

{
  "mcpServers": {
    "alpacarelay-email": {
      "type": "streamableHttp",
      "url": "https://app.alpacarelay.com/api/mcp",
      "disabled": false
    }
  }
}

Keep "type": "streamableHttp". Without it Cline falls back to the older SSE transport.

In the terminal, run goose configure, choose Add Extension → Remote Extension (Streamable HTTP), name it alpacarelay-email, and paste the server URL:

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.

On the web (grok.com): open 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.

https://app.alpacarelay.com/api/mcp

Grok Build (CLI):

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.

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:

{
  "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.

Connect Manus with an API key rather than signing in.

Open Connectors → Create → Add MCP by URL. Older versions use Settings → Integrations → Custom MCP Servers → Add Server.
Name it AlpacaRelay and paste the server URL:
https://app.alpacarelay.com/api/mcp
Paste your key into the bearer-token field, or add a header Authorization with the value Bearer ar_live_….
Save and test the connection.

Any client that supports remote MCP servers over Streamable HTTP and OAuth can connect. Most JSON configs look like this:

{
  "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.

Restart your client after editing a config file. Most clients read MCP config only at startup. The first time the client connects, it opens a browser window where you sign in to AlpacaRelay and approve the connection.

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:

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

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

Claude Code
VS Code
Codex
Cursor, Cline, and others

claude mcp add --transport http alpacarelay-email \
  https://app.alpacarelay.com/api/mcp \
  --header "Authorization: Bearer ar_live_…"

VS Code can ask for the key once and store it securely, so it never sits in mcp.json:

{
  "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}" }
    }
  }
}

Codex reads the key from an environment variable, so it never sits in config.toml:

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

Add a headers entry to the server’s config:

{
  "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, which needs Node.js so that npx is available:

{
  "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

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 for what else to ask.

Troubleshooting

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.

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.

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.

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.

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

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.

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.

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.

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.

Essentials

REST API

MCP

Add the server

Choose a workspace

Connect with an API key

Clients that only run local servers

Keep your key out of the repo

Check it worked

Troubleshooting

​Add the server

​Sign in

​Choose a workspace

​How long a sign-in lasts

​Connect with an API key

​Clients that only run local servers

​Keep your key out of the repo

​Check it worked

​Troubleshooting

Add the server

Sign in

Choose a workspace

How long a sign-in lasts

Connect with an API key

Clients that only run local servers

Keep your key out of the repo

Check it worked

Troubleshooting