# MCP (/docs/api/mcp) Beai serves a [Model Context Protocol](https://modelcontextprotocol.io) endpoint at `/api/mcp`, so an AI client can read your visibility data and manage prompts without you copying numbers between windows. On cloud that is `https://app.elmohq.com/api/mcp`. A self-hosted instance serves the same endpoint on its own address, so swap `app.elmohq.com` for yours in everything below. Every deployment also documents its own connection at **Settings → MCP** in the organization's settings sidebar: the endpoint on that instance's own address, snippets for the common clients, and the tools it registers. There are two ways to connect. Signing in from the client is the quickest, and the connection then acts as you, in the workspaces you belong to. An API key is for a client that can't open a browser — a container, a scheduled job — and is also how you grant a client *less* than your own access. ## Quick setup [#quick-setup] [`add-mcp`](https://github.com/neon-solutions/add-mcp) finds the AI clients installed on your machine and adds Beai to each of them: ```bash npx add-mcp https://app.elmohq.com/api/mcp --name elmo ``` Add `-g` to install it for every project rather than just the current one, and `-y` to skip the prompt. Each client then asks you to sign in the first time it uses Beai. To set up a single client by hand, or one `add-mcp` doesn't cover, follow its section below. ## Sign in from the client [#sign-in-from-the-client] Give the client the URL and it opens a browser for you to sign in. There is no application to register first, on cloud or on your own instance. ### Claude Code [#claude-code] ```bash claude mcp add --transport http beai https://app.elmohq.com/api/mcp ``` Then run `/mcp` and choose **Authenticate**. ### Claude.ai and Claude Desktop [#claudeai-and-claude-desktop] Custom connectors are available on every Claude plan; the Free plan is limited to one. 1. Open **Customize → Connectors**, choose **+ Add**, then **Add custom connector**. 2. Name it `Beai`, set the URL to `https://app.elmohq.com/api/mcp`, and choose **Continue**. 3. Review the detected authentication settings, choose **Continue**, and choose **Add**. 4. Sign in to Beai when Claude asks. On Team and Enterprise plans, an owner adds the connector first under **Organization settings → Connectors**, choosing **Add**, then **Custom → Web**. Members then find it under **Customize → Connectors** and choose **Connect**. ### ChatGPT [#chatgpt] Custom MCP servers are added from ChatGPT on the web, and workspace admins can restrict them. 1. Open [Plugins](https://chatgpt.com/plugins), choose **+**, then **Add custom MCP server**. 2. Name it `Beai`, set the server URL to `https://app.elmohq.com/api/mcp`, and choose **OAuth** for authentication. 3. Confirm the warning with **I understand and want to continue**, then choose **Create as a plugin**. 4. Install the plugin and sign in to Beai. ### Codex [#codex] ```bash codex mcp add elmo --url https://app.elmohq.com/api/mcp codex mcp login beai ``` ### Cursor [#cursor] [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=elmo&config=eyJ1cmwiOiJodHRwczovL2FwcC5lbG1vaHEuY29tL2FwaS9tY3AifQ%3D%3D) Or put it in `~/.cursor/mcp.json`, or `.cursor/mcp.json` for a single project: ```json { "mcpServers": { "elmo": { "url": "https://app.elmohq.com/api/mcp" } } } ``` Cursor shows the server as needing login; sign in from there. Older Cursor releases send a callback Beai can't accept, so if signing in fails, use an API key instead. ### VS Code [#vs-code] [Add to VS Code](vscode:mcp/install?%7B%22name%22%3A%22elmo%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapp.elmohq.com%2Fapi%2Fmcp%22%7D) Or from a terminal: ```bash code --add-mcp '{"name":"elmo","type":"http","url":"https://app.elmohq.com/api/mcp"}' ``` Or run **MCP: Add Server** from the Command Palette, choose **HTTP**, and enter the URL. Or put it under `servers` in `mcp.json`: ```json { "servers": { "elmo": { "type": "http", "url": "https://app.elmohq.com/api/mcp" } } } ``` VS Code asks you to sign in the first time it starts the server. ### Devin Desktop [#devin-desktop] Devin Desktop, formerly Windsurf, shares its MCP servers with Devin CLI: ```bash devin mcp add -s user elmo https://app.elmohq.com/api/mcp devin mcp login beai ``` Or put it in `~/.config/devin/mcp_config.json`: ```json { "mcpServers": { "elmo": { "url": "https://app.elmohq.com/api/mcp" } } } ``` ### Antigravity [#antigravity] Antigravity's IDE and CLI, which replaced Gemini CLI, read `~/.gemini/config/mcp_config.json`: ```json { "mcpServers": { "elmo": { "serverUrl": "https://app.elmohq.com/api/mcp" } } } ``` To sign in, open **Agent settings → Customizations** and choose **Authenticate** next to Beai. After signing in, Antigravity shows a code in the browser; paste it back into the settings panel and choose **Submit**. ### OpenCode [#opencode] In `opencode.json`, or `~/.config/opencode/opencode.json` for every project: ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "elmo": { "type": "remote", "url": "https://app.elmohq.com/api/mcp", "enabled": true } } } ``` Then `opencode mcp auth elmo`. ### Goose [#goose] [Add to Goose](goose://extension?url=https%3A%2F%2Fapp.elmohq.com%2Fapi%2Fmcp&type=streamable_http&id=beai&name=Beai&description=Read%20your%20AI%20visibility%20data%20and%20manage%20prompts%20in%20Beai) Or run `goose configure`, choose **Add Extension → Remote Extension (Streamable HTTP)**, and enter the URL. ### Other clients [#other-clients] Any client that supports remote MCP servers over Streamable HTTP with OAuth can connect: give it `https://app.elmohq.com/api/mcp` and sign in when it asks. A client that only runs local servers can reach Beai through [`mcp-remote`](https://www.npmjs.com/package/mcp-remote): ```json { "mcpServers": { "elmo": { "command": "npx", "args": ["-y", "mcp-remote", "https://app.elmohq.com/api/mcp"] } } } ``` ## Or use an API key [#or-use-an-api-key] Issue one from **Settings → API Keys** in the organization's settings sidebar — keys belong to the organization, so they are not found under a brand. Issue it read-only and optionally narrow it to selected brands. Send it as a bearer token. ChatGPT only connects by signing in; Claude.ai and Claude Desktop take the key when you add the connector: choose **No sign in** under **Authentication** and add an `Authorization: Bearer elmo_...` request header. `add-mcp` takes it as a header for every client it configures: ```bash npx add-mcp https://app.elmohq.com/api/mcp --name elmo \ --header "Authorization: Bearer elmo_..." ``` Claude Code: ```bash claude mcp add --transport http beai https://app.elmohq.com/api/mcp \ --header "Authorization: Bearer elmo_..." ``` Codex, which reads the key from the environment rather than the config file: ```bash codex mcp add elmo --url https://app.elmohq.com/api/mcp \ --bearer-token-env-var ELMO_API_KEY ``` Cursor, in `~/.cursor/mcp.json`: ```json { "mcpServers": { "elmo": { "url": "https://app.elmohq.com/api/mcp", "headers": { "Authorization": "Bearer elmo_..." } } } } ``` VS Code, in `mcp.json`: ```json { "servers": { "elmo": { "type": "http", "url": "https://app.elmohq.com/api/mcp", "headers": { "Authorization": "Bearer elmo_..." } } } } ``` Devin Desktop and Devin CLI, in `~/.config/devin/mcp_config.json`: ```json { "mcpServers": { "elmo": { "url": "https://app.elmohq.com/api/mcp", "headers": { "Authorization": "Bearer elmo_..." } } } } ``` Antigravity, in `~/.gemini/config/mcp_config.json`: ```json { "mcpServers": { "elmo": { "serverUrl": "https://app.elmohq.com/api/mcp", "headers": { "Authorization": "Bearer elmo_..." } } } } ``` OpenCode, in `opencode.json`: ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "elmo": { "type": "remote", "url": "https://app.elmohq.com/api/mcp", "enabled": true, "headers": { "Authorization": "Bearer elmo_..." } } } } ``` ## Self-hosting [#self-hosting] Nothing has to be turned on — the endpoint is there as soon as the instance is, and signing in from a client works against your instance the same way it does against cloud. The one thing that has to be right is `APP_URL`: it must be the address clients actually reach you on, because that is where the sign-in flow is advertised from and what the tokens it issues are bound to. It has to be an HTTPS URL, or `localhost` — the app refuses to start otherwise, since a token bound to anything else is one no MCP client will accept. Keys come from the same organization settings page as on cloud, and instance-wide admin keys can also be configured server-side through the `ADMIN_API_KEYS` environment variable. ## Try [#try] > What is the visibility and share of voice for each tagged prompt in Beai for ``? > What are some AEO opportunities for my ``? > Give me an example run for my `` prompt. For a full measure-diagnose-fix workflow on top of this data, install the [skill](/docs/api/skill). ## Scopes [#scopes] A connection is only offered the tools its scopes allow, so a client is never shown something it would then be refused: | Scope | MCP tool | | --- | --- | | *(none)* | `whoami`, `list_models` | | `read` | `list_brands`, `get_brand`, `list_competitors`, `list_prompts`, `list_prompt_tags`, `get_analytics`, `get_prompt_performance`, `get_citations`, `get_query_fanout`, `get_opportunities`, `list_runs`, `get_run`, `get_billing` | | `write` | `create_prompts`, `update_prompt` | A read-write key can create and edit prompts over MCP, but no tool deletes data and no tool changes billing — those are [REST API](/docs/api) concerns or reserved for an instance admin key entirely. A connection you signed in from acts as you and reaches everything you can, so scopes are a property of a key rather than of the sign-in.