Run agents over MCP

The Agents API ships an official Model Context Protocol server, so hosts like Cursor, Claude Code, VS Code, Codex, and Hermes can run and manage H agents as tools.


Transport	Remote streamable HTTP at `/mcp` on your region’s host
Auth	Your H API key as `Authorization: Bearer hk-...`
Works with	Any client that can send a bearer header
Not supported	Clients that require OAuth, like Claude.ai web or the ChatGPT app

Add to your editor

One click installs the hai-agents server. Paste your API key when prompted. These buttons target the EU region (the default):

Add to Cursor

Opens Cursor and prompts to install.

Add to VS Code

Opens VS Code and prompts to install.

US region: Add to Cursor or Add to VS Code. Registry-aware clients also find it in the MCP Registry as io.github.hcompai/hai-agents. With the hai CLI, hai mcp install wires the server into every detected client (Cursor, VS Code, VS Code Insiders, Claude Code, Hermes, Windsurf). Pass a client id to target one (hai mcp install cursor), or list to see the ids. It writes your API key into each config in plaintext.

Connect manually

Point your client at the /mcp URL for your region with the Authorization header:

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "hai-agents": {
      "url": "https://agp.eu.hcompany.ai/mcp",
      "headers": { "Authorization": "Bearer hk-..." }
    }
  }
}

claude mcp add --scope user --transport http hai-agents https://agp.eu.hcompany.ai/mcp \
  --header "Authorization: Bearer hk-..."

// user mcp.json (MCP: Open User Configuration)
{
  "servers": {
    "hai-agents": {
      "type": "http",
      "url": "https://agp.eu.hcompany.ai/mcp",
      "headers": { "Authorization": "Bearer hk-..." }
    }
  }
}

# ~/.codex/config.toml
[mcp_servers.hai-agents]
url = "https://agp.eu.hcompany.ai/mcp"
bearer_token_env_var = "HAI_API_KEY"   # export HAI_API_KEY=hk-...

# ~/.hermes/config.yaml
mcp_servers:
  hai-agents:
    url: https://agp.eu.hcompany.ai/mcp
    headers:
      Authorization: "Bearer hk-..."

Your API key is a secret: keep it in your local client config, never in a committed or shared workspace file.
In a network-restricted sandbox (for example NVIDIA NemoClaw / OpenShell), allow your region’s /mcp host in the egress policy, scoped to the calling process. See the NemoClaw example.

Tools

Tool	What it does
`run_agent`	Start an agent on a task. Returns the answer, or a session handle to wait on if the task runs long.
`wait_for_session`	Long-poll a session for its answer, or fetch its current snapshot.
`list_agents`	List the agents you can run: your org’s plus the public `h/` ones. Pass an agent’s `name` as `agent` to `run_agent`.
`send_message`	Send a follow-up message to a running session.
`cancel_session`	Cancel a session.
`share_session`	Make a session publicly viewable and return a share link.
`list_files`	List files in a cloud browser’s `~/Downloads`, newest first. Takes the browser session id, not the agent session id. See Session files.
`read_file`	Read a file from the browser’s machine, base64-encoded.
`write_file`	Write a base64-encoded file onto the browser’s machine for the agent to use.

Get started

Concepts

Browser and desktop

Integrations

Guides

Operate

Add to your editor

Add to Cursor

Add to VS Code

Connect manually

Tools

​Add to your editor

Add to Cursor

Add to VS Code

​Connect manually

​Tools

Add to your editor

Connect manually

Tools