Heliyos

Heliyos MCP server

Connect AI agents to Heliyos , the AI operating system for revenue.

@heliyos/heliyos-mcp is a Model Context Protocol server for Heliyos. It runs on your machine over stdio and calls the Heliyos API with a workspace API key, so an agent in Claude Code, Codex, Cursor, VS Code, Antigravity or any other MCP client can work in your CRM.

Documentation: [docs.heliyos.ai/mcp](https://docs.heliyos.ai/mcp/overview) · Install guides · All tools · API reference · Changelog

With it, an agent can:

• find and update companies, people, deals and custom objects, and add fields to them
• read a record's timeline, change history, emails and meetings
• write notes and tasks, and start Heliyos workers on a task
• list the reviews waiting for a person and approve or reject them
• create and configure workers from the trigger and tool catalogs
• manage scouts, read their signals and keep the watchlist
• read and edit the knowledge base, and upload the files the workers read
• hand a job to Heliyos with heliyos_ask and follow the run

Important actions that workers take still wait for review in Heliyos, so the team stays in control.

Quick start

1. Create an API key in Heliyos under Settings → API keys (details below).
2. Add the server to your client. For Claude Code:

   claude mcp add --transport stdio --env HELIYOS_API_KEY=YOUR_HELIYOS_API_KEY --scope user heliyos -- npx -y @heliyos/heliyos-mcp

1. Ask your agent *"Which Heliyos workspace am I connected to?"*. It calls heliyos_organization_get and answers with your workspace name.

Every other client is covered in Install.

Contents

• Quick start
• Before you start
• Install
• Tool timeout
• Configuration
• Tools
• Security
• Troubleshooting
• Development
• Contributing
• License

Before you start

You need Node.js 20 or later (node -v) and a Heliyos API key.

To create a key:

1. Open Heliyos and go to Settings → API keys (gtm.heliyos.ai/settings/api-keys).
2. Click New key. Give it a name you will recognise, such as "Claude Code on my laptop", and an expiry date if you want one, then click Create key.
3. Copy the key. It starts with heliyos_ and is shown once. If you lose it, revoke it and create a new one.

Only workspace owners and admins can create keys. A key has admin access to one workspace, the one you created it in, and to nothing else. Use one key per person and machine, so you can revoke one without breaking the others.

Install

Every client runs the same command, npx -y @heliyos/heliyos-mcp, with your key in the HELIYOS_API_KEY environment variable. In the snippets below, replace YOUR_HELIYOS_API_KEY with your key.

Claude Code

Install the plugin and set your key in one go. The key goes into your system's secure credential store, never into a file, and the plugin adds a skill that teaches Claude when to use which tool.

claude plugin marketplace add heliyos-ai/heliyos-mcp

claude plugin install heliyos@heliyos --config api_key=YOUR_HELIYOS_API_KEY

If you installed without --config, the server stays off until the key is set: run /plugin configure heliyos@heliyos inside Claude Code and enter it there. Then /mcp lists heliyos, or restart Claude Code if it does not.

Or add only the MCP server:

claude mcp add --transport stdio --env HELIYOS_API_KEY=YOUR_HELIYOS_API_KEY --scope user heliyos -- npx -y @heliyos/heliyos-mcp

Check it with claude mcp list, or /mcp inside a session.

Claude Desktop

Open Settings → Developer → Edit Config and add the server to claude_desktop_config.json, then restart Claude Desktop:

{

"mcpServers": { "heliyos": { "command": "npx", "args": ["-y", "@heliyos/heliyos-mcp"], "env": { "HELIYOS_API_KEY": "YOUR_HELIYOS_API_KEY" } } } }

This file stores the key in plain text, so keep it private. Custom connectors on claude.ai and in the Claude connector directory need a hosted (remote) MCP server with OAuth. Heliyos does not offer one yet, so use a local client for now.

Codex

Add the server to ~/.codex/config.toml:

[mcp_servers.heliyos]

command = "npx" args = ["-y", "@heliyos/heliyos-mcp"] env_vars = ["HELIYOS_API_KEY"] startup_timeout_sec = 30 tool_timeout_sec = 120

env_vars passes HELIYOS_API_KEY from the shell you start Codex in, so export it there (for example in ~/.zshrc). To keep the key in the file instead, replace the env_vars line with an env table at the end:

[mcp_servers.heliyos.env]

HELIYOS_API_KEY = "YOUR_HELIYOS_API_KEY"

The CLI does the same in one line, after which you add tool_timeout_sec = 120 to the table it writes:

codex mcp add heliyos --env HELIYOS_API_KEY=YOUR_HELIYOS_API_KEY -- npx -y @heliyos/heliyos-mcp

Cursor

Add Heliyos to Cursor

The link opens this deeplink, which you can also paste into your browser:

cursor://anysphere.cursor-deeplink/mcp/install?name=heliyos&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBoZWxpeW9zL2hlbGl5b3MtbWNwIl0sImVudiI6eyJIRUxJWU9TX0FQSV9LRVkiOiIke2VudjpIRUxJWU9TX0FQSV9LRVl9In19

It adds this entry to ~/.cursor/mcp.json:

{

"mcpServers": { "heliyos": { "type": "stdio", "command": "npx", "args": ["-y", "@heliyos/heliyos-mcp"], "env": { "HELIYOS_API_KEY": "${env:HELIYOS_API_KEY}" } } } }

Cursor reads ${env:HELIYOS_API_KEY} from its own environment. Export the variable in your shell profile and start Cursor from that shell, or replace the value with your key. Run npm run install-links in this repository to print the links again.

VS Code

Install Heliyos in VS Code

The link opens this deeplink, which you can also paste into your browser:

vscode:mcp/install?%7B%22name%22%3A%22heliyos%22%2C%22inputs%22%3A%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22heliyos-api-key%22%2C%22description%22%3A%22Heliyos%20API%20key%20(Settings%20%E2%86%92%20API%20keys)%22%2C%22password%22%3Atrue%7D%5D%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40heliyos%2Fheliyos-mcp%22%5D%2C%22env%22%3A%7B%22HELIYOS_API_KEY%22%3A%22%24%7Binput%3Aheliyos-api-key%7D%22%7D%7D)%22%2C%22password%22%3Atrue%7D%5D%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40heliyos%2Fmcp%22%5D%2C%22env%22%3A%7B%22HELIYOS_API_KEY%22%3A%22%24%7Binput%3Aheliyos-api-key%7D%22%7D%7D

VS Code asks for the key the first time the server starts and keeps it in its secret storage. To set it up by hand, add this to .vscode/mcp.json in a project, or to your user mcp.json (MCP: Open User Configuration):

{

"inputs": [ { "type": "promptString", "id": "heliyos-api-key", "description": "Heliyos API key (Settings → API keys)", "password": true } ], "servers": { "heliyos": { "type": "stdio", "command": "npx", "args": ["-y", "@heliyos/heliyos-mcp"], "env": { "HELIYOS_API_KEY": "${input:heliyos-api-key}" } } } }

Antigravity

In the agent panel, open … → MCP Servers → Manage MCP Servers → View raw config, or edit ~/.gemini/config/mcp_config.json directly (.agents/mcp_config.json for one project):

{

"mcpServers": { "heliyos": { "command": "npx", "args": ["-y", "@heliyos/heliyos-mcp"], "env": { "HELIYOS_API_KEY": "YOUR_HELIYOS_API_KEY" } } } }

Any other client

Run the package over stdio with the key in the environment:

HELIYOS_API_KEY=YOUR_HELIYOS_API_KEY npx -y @heliyos/heliyos-mcp

The repository also ships portable Agent Plugins manifests (plugin.json and mcp.json) for clients that install plugins from a Git repository. They do not carry a key, so set HELIYOS_API_KEY in the environment your client starts servers with. In the MCP Registry the server is listed as ai.heliyos/heliyos-mcp.

Tool timeout

heliyos_ask waits up to 90 seconds for Heliyos to answer, so give tool calls at least 120 seconds.

When a client cuts a call short, the run keeps going in Heliyos. Find it with heliyos_runs_list and follow it with heliyos_runs_get and wait: true, which waits up to 30 seconds per call.

A rate-limited request (HTTP 429) is retried once after the Retry-After delay, capped at 30 s, so a heliyos_ask that hits the limit can take about 125 seconds. If you see timeouts while you are near the limit, raise the timeout to 150 seconds.

Configuration

| HELIYOS_MCP_EXPERIMENTAL | No | Off | 1, `t