helmlane
Download
Documentation

Guide

Use Helmlane from other agents

The Helmlane MCP server gives Claude Code, Cursor, Codex or VS Code your computers: list them, read chats, and send work to any agent running on them.

1. Connect this computer, once

Run the login command. Nothing needs installing first:

Terminal
npx -y @helmlane/mcp-server login

Or install it once and use the helmlane-mcp command directly:

Terminal
npm install -g @helmlane/mcp-server
helmlane-mcp login

It prints a link and a code:

Output
  Connect Helmlane to this computer

  1  Open    https://app.helmlane.com/connect
  2  Enter   BCDF-GHJK
  1. Open the link on your phone or in any browser where you are signed in to Helmlane (helmlane.com/connect leads to the same page).
  2. Check that the code matches what your terminal shows.
  3. Choose what the connection may do — read (computers, projects, chats, runs, costs) or read and dispatch (also send work, answer agents, stop runs, start races) — and how long it lasts: 30, 90 or 365 days.
  4. Approve. If your account has a passkey or an authenticator, Helmlane asks for it first.

The token is stored in your operating system’s keychain — the macOS login keychain, or the Secret Service keyring through secret-tool on Linux. Where neither exists it is stored in ~/.config/helmlane/credentials.jsonwith mode 0600, and the command says so. It never appears on a command line, in a log or in a tool result.

OptionEffect
--read-onlyAsk only for read
--origin URLA self-hosted control plane (default https://api.helmlane.com)
--no-browserDo not open the link automatically

2. Add it to your agent

Once you have logged in, the server needs no environment variables.

Claude Code

Terminal
claude mcp add --scope user helmlane -- npx -y @helmlane/mcp-server

Cursor

~/.cursor/mcp.json (or .cursor/mcp.json in a project)
{
  "mcpServers": {
    "helmlane": { "command": "npx", "args": ["-y", "@helmlane/mcp-server"] }
  }
}

Codex

~/.codex/config.toml
[mcp_servers.helmlane]
command = "npx"
args = ["-y", "@helmlane/mcp-server"]

VS Code

.vscode/mcp.json
{
  "servers": {
    "helmlane": { "type": "stdio", "command": "npx", "args": ["-y", "@helmlane/mcp-server"] }
  }
}

helmlane-mcp config <claude-code|cursor|codex|vscode> prints the same snippets.

3. Use it

Ask your agent something like:

Use Helmlane to ask Codex on my studio Mac to fix the flaky test in the api project, then show me what it changed.

Some answers are deliberately honest rather than tidy. A run whose outcome cannot be known reports outcome_unknown, never “completed”. A cost an agent does not report is “unknown”, never zero. And dispatch refuses to guess when a project lives on two computers — it lists the choices instead.

Tools

ToolScopeWhat it does
list_machinesreadYour computers, whether they are available, and the agents on each — health, models, whether they can start chats.
list_projectsreadProjects and their placements (a folder on a computer).
list_chatsreadChats in a project, newest first, with work in flight.
read_chatreadOne page of a transcript; ask for older pages as needed.
dispatchdispatchSend a prompt: follow up in a chat, or start a new one in a project, optionally choosing placement, agent and model.
get_run_statusreadState of a submission, pending questions, and the reply so far.
wait_for_runreadWait up to ten minutes until it finishes or needs you, reporting progress.
respond_to_interactiondispatchApprove, decline or answer what the agent is waiting on.
cancel_rundispatchStop a running submission or withdraw a queued one.
start_racedispatchOne prompt to two or three agents, each in its own git worktree.
cost_summaryreadTokens and cost by agent and model over the last N days.

A read-only connection only lists the read tools.

Manage the connection

Terminal
helmlane-mcp status    # account, token name, scopes, expiry, last use, where it's stored
helmlane-mcp logout    # revoke the token on the server and delete it locally
helmlane-mcp config cursor    # print the setup snippet: claude-code, cursor, codex or vscode

Every connection also appears in the Helmlane app under Settings → API tokens, with its last use and a history of requests. Revoking it there takes effect on the very next request, including one already in flight. “Sign out everywhere else” revokes it too.

CI and containers

Where there is no keychain or browser, give the server a token through the environment instead:

Terminal
export HELMLANE_API_TOKEN=…            # instead of logging in
export HELMLANE_URL=https://helmlane.example.com   # only for a self-hosted server

Against your own server, log in with its origin:

Terminal
npx -y @helmlane/mcp-server login --origin https://helmlane.example.com

How it is built

  • A client like any other. Every tool is an HTTPS call to the same API the phone app uses. The package cannot reach a database, a server module or a computer’s credential.
  • Scoped, revocable, audited. The token is created through a device authorization you approve, stored only as a hash on the server, checked against an explicit allowlist on every request, and every use is recorded. Anything not on the list — security settings, sessions, terminals, port forwards, removing computers — is refused.
  • Same rules as your phone. Dispatch goes through the same draft, prepare and submit steps as the app, so queueing and write ownership behave identically, and it never overwrites a draft you are typing on another device.
  • Strict arguments. Unknown argument names are rejected, not silently dropped.