# Connect the MCP server > Connect Claude Code, Claude Desktop, ChatGPT, Cursor, VS Code or any MCP client to your Emelia account, by signing in or with an API key. 143 tools in 8 categories, for campaigns, lists, enrichment, LinkedIn extractions, mailboxes and the inbox. Source: https://docs.emelia.io/docs/mcp The Emelia MCP server lets an AI assistant work in your Emelia account in plain language: "add these three prospects to my SaaS founders list", "what is the reply rate of my Q4 campaign this week?", "draft a reply to the last email from Nexora". It covers the whole Emelia API except the legacy campaigns: 82 tools for campaigns and their sequences, lists and contacts, enrichment, LinkedIn extractions, sending mailboxes and your account. Once the Inbox is set up, 61 more tools read, sort and answer the emails of your inbox. That makes 143 tools, in [8 categories](https://docs.emelia.io/docs/mcp/categories.md) you can turn on one by one. | | | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | URL | `https://mcp.emelia.io/mcp` | | Transport | Streamable HTTP, stateless (`POST` only) | | Authentication | Sign in with your Emelia account (OAuth), or your Emelia API key in the `Authorization` header (raw or `Bearer `) or in `X-Api-Key`. See [Authentication](#authentication). | | Tool categories | All by default, or the ones you list with `?toolsets=`. See [Tool categories](https://docs.emelia.io/docs/mcp/categories.md). | | Health check | `https://mcp.emelia.io/mcp/health` answers `{"ok":true}` | Most clients sign you in with your Emelia account the first time they connect: you add the URL, an Emelia page opens in your browser, and you click **Authorize**. There is nothing to copy. An [API key](#with-an-api-key) is only needed for scripts, CI, and clients that cannot sign in. Whatever the client, name the server `emelia`: the tools then show up as `mcp__emelia__`, the names the [Claude Code plugin](https://docs.emelia.io/docs/ai/claude-code-plugin.md) expects. ## Install Claude loads the tools it needs on demand: in Claude Code, Claude Desktop and claude.ai, connect the plain URL and keep every tool. Cursor, VS Code and most other clients send the description of every tool to the model with each message, and some cap the number of tools: give them only the categories you need, with `?toolsets=`. **Claude Code** **Categories**: all of them, no parameter. Claude Code loads the tools on demand. For yourself, in every project: ```bash claude mcp add --transport http --scope user emelia https://mcp.emelia.io/mcp ``` Then run `/mcp` in Claude Code, pick `emelia` and choose **Authenticate**. Your browser opens Emelia: check the account shown and click **Authorize**. Back in Claude Code, `emelia` shows as connected. Ask "list my campaigns" to test it. For a shared project, commit a `.mcp.json` at the root. It holds no secret: each person signs in with their own Emelia account, with `/mcp`, the first time. ```json title=".mcp.json" { "mcpServers": { "emelia": { "type": "http", "url": "https://mcp.emelia.io/mcp" } } } ``` **With an API key** (CI, scripts, a machine without a browser), pass it in a header. Claude Code then does not ask you to sign in: ```bash claude mcp add --transport http --scope user emelia https://mcp.emelia.io/mcp \ --header "Authorization: YOUR_EMELIA_API_KEY" ``` In a shared `.mcp.json`, reference a variable, not the key: `"headers": { "Authorization": "${EMELIA_API_KEY}" }`, and each person keeps the key in their environment (`export EMELIA_API_KEY=YOUR_EMELIA_API_KEY`). The server checks the key at the first tool call, not when `/mcp` shows the server as connected. **Claude Desktop** **Categories**: all of them, no parameter. Claude loads the tools on demand, in Claude Desktop as on claude.ai. **Custom connector**, nothing to install: **Customize, Connectors, Add, Add custom connector** (Pro and Max plans; on Team and Enterprise an owner adds it in the organization settings). * Name: `emelia` * URL: `https://mcp.emelia.io/mcp` Leave the advanced settings empty and add the connector. Then click **Connect**: the Emelia page opens, click **Authorize**. The connector belongs to your Claude account: it works in Claude Desktop and on claude.ai. The calls then come from Anthropic's cloud, not from your computer. On Team and Enterprise, the owner adds the connector once, and each member connects their own Emelia account. **Or the configuration file**, with an API key (`claude_desktop_config.json`, opened from **Settings, Developer, Edit Config**; quit and restart the app after saving). This file only starts local servers, so it uses the `mcp-remote` bridge, which needs Node 18 or later: ```json title="claude_desktop_config.json" { "mcpServers": { "emelia": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.emelia.io/mcp", "--header", "Authorization:${EMELIA_API_KEY}" ], "env": { "EMELIA_API_KEY": "YOUR_EMELIA_API_KEY" } } } } ``` **ChatGPT** **Categories**: only the ones you need, to keep the list of tools short. Add `?toolsets=` to the URL, for example `https://mcp.emelia.io/mcp?toolsets=campaigns,lists,inbox`. See [Tool categories](https://docs.emelia.io/docs/mcp/categories.md). ChatGPT adds MCP servers in developer mode, on the paid plans: turn it on in **Settings, Apps & Connectors, Advanced settings, Developer mode**, then create a connector: * Name: `Emelia` * URL: `https://mcp.emelia.io/mcp?toolsets=campaigns,lists,inbox` * Authentication: **OAuth** ChatGPT opens the Emelia page: click **Authorize**. The Emelia tools then show up in the tools of your conversations. **Cursor** **Categories**: only the ones you need. Cursor sends every active tool to the model, so add `?toolsets=` to the URL, for example `https://mcp.emelia.io/mcp?toolsets=campaigns,lists,enrichment`. See [Tool categories](https://docs.emelia.io/docs/mcp/categories.md) for the list and ready-made combinations. [Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=emelia&config=eyJ1cmwiOiJodHRwczovL21jcC5lbWVsaWEuaW8vbWNwIn0%3D) The button opens Cursor with the server ready to add, with every category. Add `?toolsets=` to the URL in the MCP configuration of Cursor. Cursor then shows that `emelia` needs a sign-in, in its MCP settings: start it, and click **Authorize** on the Emelia page. Or add it by hand to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project): ```json title="~/.cursor/mcp.json" { "mcpServers": { "emelia": { "url": "https://mcp.emelia.io/mcp?toolsets=campaigns,lists,enrichment" } } } ``` **With an API key**, Cursor does not ask you to sign in: add `"headers": { "Authorization": "${env:EMELIA_API_KEY}" }` next to `url`, and keep the key in the `EMELIA_API_KEY` variable of your environment. **VS Code** **Categories**: only the ones you need. VS Code sends every active tool to the model, so add `?toolsets=` to the URL, for example `https://mcp.emelia.io/mcp?toolsets=campaigns,inbox`. See [Tool categories](https://docs.emelia.io/docs/mcp/categories.md) for the list and ready-made combinations. [Install in VS Code](https://insiders.vscode.dev/redirect/mcp/install?name=emelia&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.emelia.io%2Fmcp%22%7D) The button opens VS Code with the server ready to install, with every category. Add `?toolsets=` to the URL in the configuration it creates. When the server starts, VS Code asks you to allow the sign-in to `mcp.emelia.io`: accept, then click **Authorize** on the Emelia page. Or configure it in `.vscode/mcp.json` (or with the command **MCP: Open User Configuration**): ```json title=".vscode/mcp.json" { "servers": { "emelia": { "type": "http", "url": "https://mcp.emelia.io/mcp?toolsets=campaigns,inbox" } } } ``` **With an API key**, VS Code asks for the key the first time the server starts and stores it securely: ```json title=".vscode/mcp.json" { "inputs": [ { "type": "promptString", "id": "emelia-api-key", "description": "Emelia API key", "password": true } ], "servers": { "emelia": { "type": "http", "url": "https://mcp.emelia.io/mcp?toolsets=campaigns,inbox", "headers": { "Authorization": "${input:emelia-api-key}" } } } } ``` **Other clients** Any client that supports remote MCP servers over Streamable HTTP works: * URL: `https://mcp.emelia.io/mcp` * Sign-in: OAuth 2.1 with PKCE (`S256`) and dynamic client registration. Without credentials, the server answers `401` with a `WWW-Authenticate` header that points to `https://mcp.emelia.io/.well-known/oauth-protected-resource/mcp`, where the client finds the rest. * Or a header: `Authorization: `, or `X-Api-Key: ` if your client reserves `Authorization`. **Categories**: if the client sends every tool to the model, which most do, add `?toolsets=` to the URL with the categories you need, for example `https://mcp.emelia.io/mcp?toolsets=inbox`. See [Tool categories](https://docs.emelia.io/docs/mcp/categories.md). Every request must accept both `application/json` and `text/event-stream`. To check the server and your key by hand, see [Check the connection](#check-the-connection). ## Authentication ### Sign in with your Emelia account The first time it connects, the client opens an Emelia page in your browser. Sign in to Emelia if needed, check the account shown on the page, and click **Authorize**: you are sent back to the client, connected. The page waits 10 minutes; after that, start the connection again from the client. The assistant then acts as you, as it would with an API key: it reads and changes your campaigns, lists, contacts and mailboxes, sends emails and spends your credits, within the same [per minute quota](https://docs.emelia.io/docs/rate-limits.md). The inbox tools work the same way. The access lasts 30 days, and most clients renew it on their own: they stay connected as long as you use them at least once every 180 days. A client that does not renew it asks you to sign in again after 30 days. To see the assistants connected to your account, or to cut the access of one of them, open **Settings, API & Webhooks, Connected apps** in the [Emelia app](https://v3.emelia.io) and click **Disconnect**. The assistant loses access within 30 seconds. ### With an API key An API key suits scripts, CI, a machine without a browser, or a client that cannot sign in with OAuth. Pass it in the `Authorization` header (raw or `Bearer `), or in `X-Api-Key`. With a key, the client does not ask you to sign in. [Get your API key](https://v3.emelia.io/settings/api) ## The inbox tools The 61 tools of the `inbox` and `inbox_settings` categories work on the Inbox of your Emelia account: they read, sort and answer its emails, and manage its labels, views and rules. They appear only once the Inbox has been opened in Emelia. The server creates nothing for you: on an account that never opened it, the server lists the 82 Emelia tools, with no error. Open the **Inbox** tab of the [Emelia app](https://v3.emelia.io/inbox) once, wait a few minutes, then reconnect the server in your client. The links these tools return open the email or the draft in the Emelia inbox, at `https://v3.emelia.io/inbox`. ## Check the connection To check the server and your key by hand, list the tools: ```bash curl -s https://mcp.emelia.io/mcp \ -H "Authorization: $EMELIA_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` With `?toolsets=`, only the tools of those categories come back: ```bash curl -s "https://mcp.emelia.io/mcp?toolsets=campaigns,inbox" \ -H "Authorization: $EMELIA_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` A wrong key still lists the Emelia tools: the key is checked at the first tool call. A misspelled category gets an HTTP `400` that lists the valid ones. Without a key, the server answers `401` with the `WWW-Authenticate` header that starts the sign-in in OAuth clients. > **Your assistant acts as you.** The assistant can change your campaigns, send emails and spend your credits. Keep the confirmations of your client on for tools that delete data, send messages or use credits.