Heliyos

[Heliyos]

Heliyos MCP server

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

[npm version] [CI] [Node 20+] [MIT license] [MCP]

@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 · 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:

   sh

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

3. 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-mcpclaude 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 = 30tool_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

The server also offers a resource template, heliyos://records/{id}, which returns one record as JSON, and two prompts: prepare_account_review (for one company) and daily_pipeline_summary.

Tools

Every tool is named heliyos_<resource>_<verb> and declares whether it reads, writes or deletes, so your client can ask before it changes anything. Reads take response_format (concise or detailed), and lists take limit and cursor.

73 tools by default, and 4 more with HELIYOS_MCP_EXPERIMENTAL=1. Kind is read (no changes), write (creates or updates) or destructive (deletes or removes).

Records

Timeline and activity

Workspace, objects and fields

Notes

Tasks

Scouts and signals

Ask, runs and reviews

Workers, triggers and tools

Knowledge base and files

Watchlist

Labels

Team

Notification settings

Usage

Security

• Your key stays on your machine. The server reads it from its environment and sends it only to the Heliyos API (HELIYOS_BASE_URL), as a bearer token over https. It refuses a base URL that is not https, other than localhost.
• File uploads skip the key. File content goes to a short-lived signed storage URL, and that request does not carry your key.
• No telemetry. The server sends nothing anywhere else and keeps no logs. Diagnostics go to your client's stderr, and error messages have keys removed.
• Rate limits. The API allows 60 requests per minute per key, and per IP address. When it answers 429, the server waits for Retry-After and retries once.
• Least access. A key has admin rights in one workspace. Give it an expiry, keep one key per person and machine, and revoke it in Settings → API keys when you no longer need it.
• Destructive tools are marked. Deletes and removals are annotated as destructive, and the agent skill tells agents to confirm them first.

Report a security issue privately through GitHub security advisories rather than in a public issue.

Troubleshooting

Still stuck? Open an issue at github.com/heliyos-ai/heliyos-mcp/issues. Never paste your key.

Development

Requirements: Node.js 20 or later and npm. Everything else is a dev dependency.

git clone https://github.com/heliyos-ai/heliyos-mcp.gitcd heliyos-mcpnpm cinpm test                  # unit tests with a mocked Heliyos APInpm run typechecknpm run build             # codegen, then tsc into dist/npm run readme:tools      # regenerate the tool table abovenpm run install-links     # print the Cursor and VS Code install linksnpm run prepublish:check  # manifests, versions and package contentsHELIYOS_API_KEY=YOUR_HELIYOS_API_KEY npm run smoke   # read-only checks against a real workspace

To run your local build in a client instead of the published package, point the client at dist/src/bin/stdio.js:

claude mcp add --transport stdio --env HELIYOS_API_KEY=YOUR_HELIYOS_API_KEY --scope user heliyos-dev -- node /path/to/heliyos-mcp/dist/src/bin/stdio.js

How it is built

• src/client/openapi/ holds copies of the Heliyos API's OpenAPI documents. npm run codegen turns them into a typed operation table (src/client/generated.ts) with zod schemas, so every request is validated before it is sent.
• src/tools/ defines one file per resource. Each tool declares its input and output schemas, its annotations (read, write or destructive) and a handler that calls one or two API operations and renders a short text plus structuredContent.
• tests/ runs every tool against a mocked API with msw. A snapshot test pins the public tool contract (names, annotations, input keys), so an accidental change fails the build.
• skills/heliyos/SKILL.md ships with the Claude Code plugin and teaches the agent when to use which tool.

Updating the API client

When the Heliyos API changes, save the new OpenAPI documents and resync:

curl -s https://api-prod.heliyos.ai/v1/platform/openapi.json -o /tmp/platform.jsoncurl -s https://api-prod.heliyos.ai/v1/auth/openapi.json -o /tmp/auth.jsonHELIYOS_PLATFORM_OPENAPI=/tmp/platform.json HELIYOS_AUTH_OPENAPI=/tmp/auth.json npm run sync-openapinpm run codegen && npm test

With those two variables set, npm run prepublish:check and the drift test also refuse a bundled copy that no longer matches.

Releasing

Releases are published by GitHub Actions on every push to main (.github/workflows/publish-package.yml):

1. CI builds, tests and checks the package and manifests.
2. If the version in package.json is already on npm, the workflow bumps the patch version with node scripts/set-version.mjs, which keeps package.json, the lockfile, server.json, every plugin manifest and src/version.ts on the same version, and commits the bump.
3. It publishes to npm with provenance through npm trusted publishing (no token is stored anywhere), waits until the version is served, and then publishes server.json to the MCP registry when the MCP_PRIVATE_KEY secret is configured.

To cut a specific version, run node scripts/set-version.mjs 1.2.0, commit, and push to main. See CONTRIBUTING.md for the one-time repository setup.

Contributing

Issues and pull requests are welcome. Read CONTRIBUTING.md for the workflow, the coding rules and how to add a tool, and SECURITY.md for how to report a vulnerability. By participating you agree to the code of conduct.

License

MIT