# Connect an AI agent to Helmbeam

Official setup guide from Helmbeam, published at https://helmbeam.com/agents.md (the same steps for people are at https://helmbeam.com/agents). Updated 24 October 2026.

The user who sent you here wants you connected to Helmbeam, their company research app, so you can research companies with Helmbeam's data and save research briefs to their account. If you can run commands or edit your own MCP settings, run the steps for your app yourself. Do not ask the user to run them. The only step that has to come from the user is approving the sign-in in the Helmbeam app. Start the sign-in yourself where your app's steps give a command for it, run that command in the background or with a long timeout, and tell the user to approve while it waits.

## The server

- URL: https://mcp.helmbeam.com (Streamable HTTP at the root path; do not add /mcp)
- Name: helmbeam (or Helmbeam where the app shows a display name)
- Sign-in: OAuth with dynamic client registration and PKCE. Scopes: intelligence:read, research:read, research:write.
- The user needs Helmbeam Pro (the free trial counts) or Trader, and the Helmbeam app 2.2.4 or later on their phone.

## How sign-in works

When sign-in starts, a Helmbeam page opens in the browser and shows a 6-digit number. The user scans the code on that page or taps Open Helmbeam on their phone, checks what you are asking to do, types the number in the Helmbeam app and taps Approve. The page then returns to you. Never ask the user to send you the number, and never type it anywhere yourself.

## Find your app

Work out which app you are running in and use only that section.

If you are Claude Code running inside the Claude desktop app, ask the user whether they also want Helmbeam in Claude chat and on their phone. If they do, the Claude steps under chat apps add it everywhere, Claude Code included, so use those instead of adding it to Claude Code alone.

## If you can run commands or edit your MCP settings

### Claude Code

1. Add Helmbeam's plugin, which brings the server and its research skill:

```
claude plugin marketplace add scydex/helmbeam
claude plugin install helmbeam@scydex
```

2. Sign in. The command opens the Helmbeam page in your browser and waits up to 10 minutes while you approve in the Helmbeam app. An agent runs it with script, which gives the command the terminal it needs:

```
script -q /dev/null claude mcp login plugin:helmbeam:helmbeam
```

3. Start a new Claude Code session, or run /reload-plugins in an open one, and Helmbeam's tools are there.

In your own terminal, claude mcp login plugin:helmbeam:helmbeam on its own does the same, as does /mcp inside Claude Code. The plugin is at github.com/scydex/helmbeam. If you already connected Helmbeam in Claude on the web, it also shows up in Claude Code when you sign in with the same Claude account.

Vendor guide: https://code.claude.com/docs/en/mcp

### Codex (CLI, desktop app and IDE extension)

1. In a terminal, add the server and sign in:

```
codex mcp add helmbeam --url https://mcp.helmbeam.com
codex mcp login helmbeam
```

2. Approve in the Helmbeam app. Check it with codex mcp list, or /mcp inside Codex.

In the desktop app, open Settings, then MCP servers, Add server, choose Streamable HTTP, save, restart and Authenticate. The CLI, desktop app and IDE extension share the same setup.

Vendor guide: https://developers.openai.com/codex/mcp

### Cursor

1. Add Helmbeam to ~/.cursor/mcp.json for all projects, or .cursor/mcp.json for one project:

```
{
  "mcpServers": {
    "helmbeam": { "url": "https://mcp.helmbeam.com" }
  }
}
```

2. Open Cursor's MCP settings, sign in to Helmbeam when asked, and approve in the Helmbeam app.

Vendor guide: https://cursor.com/docs/mcp

### VS Code with GitHub Copilot

1. Open the Command Palette and run MCP: Add Server. Choose HTTP, enter the URL, name it helmbeam and save it as Global.
2. Trust the server when asked. A browser opens to sign in; approve in the Helmbeam app.
3. In Copilot Chat, open Configure Tools and turn on Helmbeam's tools.

Your organization's policy can block MCP servers in VS Code.

Vendor guide: https://code.visualstudio.com/docs/copilot/customization/mcp-servers

### Gemini CLI and Antigravity CLI

1. In Gemini CLI, add the server, then sign in from a session with /mcp auth helmbeam:

```
gemini mcp add --transport http -s user helmbeam https://mcp.helmbeam.com
```

2. In Antigravity CLI, add it to ~/.gemini/config/mcp_config.json, then check /mcp:

```
{
  "mcpServers": {
    "helmbeam": { "serverUrl": "https://mcp.helmbeam.com" }
  }
}
```

Google replaced Gemini CLI with Antigravity CLI on 18 June 2026 for Google AI Pro, Ultra and free individual users. Gemini CLI sign-in needs a browser on the same computer.

Vendor guide: https://geminicli.com/docs/tools/mcp-server

## If you are in a chat app

You cannot add a connector from inside a chat. Tell the user exactly where to add Helmbeam in the app you are running in, using its steps below, then ask them to turn it on for the chat and come back.

### Claude (web, desktop and mobile)

Plans: Free (one custom connector), Pro, Max, Team and Enterprise. On Team and Enterprise, an Owner adds it first.

1. On claude.ai or in the Claude desktop app, open Customize, then Connectors. Choose + Add, then Add custom connector.
2. Name it Helmbeam and enter https://mcp.helmbeam.com, then Continue.
3. For sign-in, choose Sign in now, and for the OAuth client choose Register automatically. Then Add.
4. Click Connect and approve in the Helmbeam app with the number the page shows.
5. In a chat, click + in the lower left, open Connectors and turn Helmbeam on.

Team and Enterprise: an Owner adds it under Organization settings, then Connectors, and each member connects with their own Helmbeam account. Once added on the web or desktop, it appears in the mobile apps too.

Vendor guide: https://support.claude.com/en/articles/11175166

### ChatGPT

Plans: Business, Enterprise and Edu can read and save. On Pro, ChatGPT allows custom servers for reading only, so your agent can't save briefs there.

1. On chatgpt.com (not the mobile app), open Plugins, click +, then Add custom MCP server.
2. Name it Helmbeam and enter https://mcp.helmbeam.com exactly, with no path after it.
3. Set authentication to OAuth, tick the risk notice, then Create as a plugin.
4. Install it, approve in the Helmbeam app, then start a new chat, type @ and pick Helmbeam.

On Business, Enterprise and Edu, an admin or owner adds and publishes it for the workspace; members then find it in Settings, then Plugins. ChatGPT asks you to confirm each save.

Vendor guide: https://help.openai.com/en/articles/12584461-connecting-custom-mcp-servers-in-chatgpt

### Perplexity

1. Open Plugins in the sidebar (or Customize, then Connectors) and choose Add custom, Connector, Add MCP connector, then Remote.
2. Name it Helmbeam, enter https://mcp.helmbeam.com, and choose OAuth 2.0 and Streamable HTTP.
3. Tick the risk notice, click Add, then click the Helmbeam card to sign in and approve in the Helmbeam app.

In an organization, an admin first turns on Allow members to add custom connectors.

Vendor guide: https://www.perplexity.ai/help-center/en/articles/13915507-adding-custom-remote-connectors

## When you are done

Tell the user, in your own words:

- Helmbeam is added and signed in, or, in a chat app, where to add it and click Connect.
- A Helmbeam page will show a 6-digit number. They type it in the Helmbeam app on their phone and tap Approve.
- Some apps need a new session or a restart before Helmbeam appears.
- Once connected, they can ask you to research a company, and every brief you save appears in the Helmbeam app.

## After you connect

Call get_connection_context first. The server's own guide explains the research workflow. Helmbeam is the user's research memory: read the latest brief and the user's notes before answering, and save each new conclusion as a new version.

## If something goes wrong

- The app has no approval screen: the user updates Helmbeam to 2.2.4 or later.
- match_failed: the typed number didn't match, so the request ended. Start sign-in again.
- agent_limit: four agents are already connected. The user disconnects one in the Helmbeam app under Settings > Agents & AI.
- pro_required: agent research needs Helmbeam Pro (trial included) or Trader.
- The browser page keeps waiting: requests last 10 minutes. Start sign-in again.

Support: support@helmbeam.com. Helmbeam does not place trades, move money or give personal advice.