> ## Documentation Index
> Fetch the complete documentation index at: https://hub.hcompany.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Run agents over MCP

> Run and manage H agents from any MCP host, no HTTP or SDK code.

export const Notice = ({kind = "note", title, children}) => {
  const kinds = {
    warning: {
      label: "User notice",
      icon: <>
          <path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3" />
          <path d="M12 9v4" />
          <path d="M12 17h.01" />
        </>
    },
    gotcha: {
      label: "Gotcha",
      icon: <>
          <circle cx="12" cy="12" r="10" />
          <path d="M12 16v-4" />
          <path d="M12 8h.01" />
        </>
    },
    note: {
      label: "Note",
      icon: <>
          <circle cx="12" cy="12" r="10" />
          <path d="M12 16v-4" />
          <path d="M12 8h.01" />
        </>
    }
  };
  const k = kinds[kind];
  return <div className="notice my-6 rounded-xl border border-zinc-200 bg-white p-5 dark:border-zinc-800 dark:bg-zinc-950">
      <div className={`${kind === "warning" ? "not-prose flex items-center gap-1.5 text-xs font-semibold uppercase tracking-wide text-red-400/80 dark:text-red-400/70" : kind === "gotcha" ? "not-prose flex items-center gap-1.5 text-xs font-semibold uppercase tracking-wide text-amber-500/80 dark:text-amber-400/70" : "not-prose flex items-center gap-1.5 text-xs font-semibold uppercase tracking-wide text-zinc-400 dark:text-zinc-500"}`}>
        <svg className="h-3.5 w-3.5" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
          {k.icon}
        </svg>
        {k.label}
      </div>
      {title && <div className="not-prose mt-2 text-base font-semibold text-zinc-900 dark:text-zinc-100">{title}</div>}
      <div className="notice-body mt-3 text-sm leading-6 text-zinc-700 dark:text-zinc-300">{children}</div>
    </div>;
};

The Agents API ships an official [Model Context Protocol](https://modelcontextprotocol.io) server, so hosts like Cursor, Claude Code, VS Code, Codex, and Hermes can run and manage H agents as tools, with no HTTP or SDK code.

|               |                                                                                   |
| ------------- | --------------------------------------------------------------------------------- |
| Transport     | Remote streamable HTTP at `/mcp` on your [region's host](/agents-api/sdks#region) |
| 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                 |

<Notice kind="note" title="Searching these docs from an AI tool?">
  That's the separate [docs MCP server](/docs-mcp-server). This page is about running agents.
</Notice>

## Add to your editor

One click installs the `hai-agents` server, then paste your [API key](/agents-api/quickstart#get-your-api-key) when prompted. The buttons target the EU region (the default):

<CardGroup cols={2}>
  <Card title="Add to Cursor" icon="https://cdn.simpleicons.org/cursor/6b6b70" href="cursor://anysphere.cursor-deeplink/mcp/install?name=hai-agents&config=eyJ1cmwiOiAiaHR0cHM6Ly9hZ3AuZXUuaGNvbXBhbnkuYWkvbWNwIiwgImhlYWRlcnMiOiB7IkF1dGhvcml6YXRpb24iOiAiQmVhcmVyIGhrLVlPVVJfS0VZIn19">
    Opens Cursor and prompts to install.
  </Card>

  <Card title="Add to VS Code" icon="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/vscode/vscode-original.svg" href="vscode:mcp/install?%7B%22name%22%3A%20%22hai-agents%22%2C%20%22type%22%3A%20%22http%22%2C%20%22url%22%3A%20%22https%3A//agp.eu.hcompany.ai/mcp%22%2C%20%22headers%22%3A%20%7B%22Authorization%22%3A%20%22Bearer%20hk-YOUR_KEY%22%7D%7D">
    Opens VS Code and prompts to install.
  </Card>
</CardGroup>

On the US region, use [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=hai-agents\&config=eyJ1cmwiOiAiaHR0cHM6Ly9hZ3AuaGNvbXBhbnkuYWkvbWNwIiwgImhlYWRlcnMiOiB7IkF1dGhvcml6YXRpb24iOiAiQmVhcmVyIGhrLVlPVVJfS0VZIn19) or [Add to VS Code](vscode:mcp/install?%7B%22name%22%3A%20%22hai-agents%22%2C%20%22type%22%3A%20%22http%22%2C%20%22url%22%3A%20%22https%3A//agp.hcompany.ai/mcp%22%2C%20%22headers%22%3A%20%7B%22Authorization%22%3A%20%22Bearer%20hk-YOUR_KEY%22%7D%7D) instead. Registry-aware clients can also find it in the [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.hcompai/hai-agents`.

## Connect manually

Point your client at the `/mcp` URL for your [region](/agents-api/sdks#region) and add the `Authorization` header.

<CodeGroup>
  ```json Cursor theme={"system"}
  // ~/.cursor/mcp.json
  {
    "mcpServers": {
      "hai-agents": {
        "url": "https://agp.eu.hcompany.ai/mcp",
        "headers": { "Authorization": "Bearer hk-..." }
      }
    }
  }
  ```

  ```bash Claude Code theme={"system"}
  claude mcp add --scope user --transport http hai-agents https://agp.eu.hcompany.ai/mcp \
    --header "Authorization: Bearer hk-..."
  ```

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

  ```toml Codex theme={"system"}
  # ~/.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-...
  ```

  ```yaml Hermes theme={"system"}
  # ~/.hermes/config.yaml
  mcp_servers:
    hai-agents:
      url: https://agp.eu.hcompany.ai/mcp
      headers:
        Authorization: "Bearer hk-..."
  ```
</CodeGroup>

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), also allow your region's `/mcp` host in the sandbox egress policy, scoped to the process that makes the call, or the agent can't reach the server. The [computer-use-agents-demos](https://github.com/hcompai/computer-use-agents-demos/tree/main/nemoclaw) repo has a worked 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 agents plus the public `h/` ones. Pass an agent's `name` as the `agent` for `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.                                                                        |

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="arrow-right" href="/agents-api/quickstart">
    Run your first session end to end with the API or SDKs.
  </Card>

  <Card title="SDKs" icon="code" href="/agents-api/sdks">
    The typed Python and TypeScript clients and the `hai` CLI.
  </Card>

  <Card title="Agents" icon="robot" href="/agents-api/agents/overview">
    Configure the agents the MCP tools run, including the public `h/` ones.
  </Card>

  <Card title="Coding assistants" icon="screwdriver-wrench" href="/agents-api/coding-skills">
    Teach your assistant the H APIs with the hai-agents skill.
  </Card>
</CardGroup>