Run and manage H Company's Computer-Use Agents from any MCP client.
io.github.hcompai/hai-agents MCP Server
This MCP server runs and manages H Company’s Computer-Use Agents from any MCP client. The server is identified by the slug io-github-hcompai-hai-agents and exposes 6 tools. Its repository description focuses on client-controlled execution and management of “computer-use agents.”
🛠️ Key Features
Runs and manages H Company “Computer-Use Agents”
Accessed from any MCP client
6 available tools
🚀 Use Cases
Controlling computer-use agents through an MCP client
Integrating H Company agents into an MCP-based workflow
⚡ Developer Benefits
Standard MCP interface for agent execution and management
Tool surface area is 6 tools for integration purposes
⚠️ Limitations
Only the server’s high-level purpose and tool count are provided; no additional capabilities, configuration, or behavior details are included in the source excerpt.
Captured live from the server via tools/list.
run_agent
Start an agent on a task; return the answer or a session handle to wait on. ``agent`` from list_agents.
pip install "hai-agents[cli]"# SDK and the holo command
pip install hai-agents # SDK only
Python 3.10 or newer is required.
Quickstart: command line
bash
pip install "hai-agents[cli]"
holo login
holo "What's the top story on Hacker News?"
holo login signs you in with Google in the browser, or takes a key you paste with holo login --key, and stores it in ~/.config/hai/.env. Any command does the same on first use in a terminal, so this step is optional. The task then runs on a hosted agent with its own browser: its steps stream to your terminal, and its answer prints at the end. In a terminal you can follow up on the same session, or run holo alone to start an interactive session.
Launch the built-in h/web-surfer-pro agent, which ships with its own browser, and describe the task in plain language. run_session polls until the agent finishes and returns the final answer.
python
from hai_agents import Client
client = Client()
result = client.run_session(
agent="h/web-surfer-pro",
messages="What are the top 3 stories on Hacker News right now?",
)
print(result.status)
print(result.answer)
Client() reads HAI_API_KEY from the environment, else the key holo login stored in ~/.config/hai/.env.
result is a SessionRunResult: id, status, answer, the accumulated events, and final_changes.
Command line
The cli extra installs the holo command, also available as hai.
bash
holo "What's the top story on Hacker News?"# run one task
holo # interactive session
holo -a h/web-surfer-pro "Compare 3 laptops"# pick an agent for one run
holo agents use h/web-surfer-pro # change the default agent
holo -a h/holo-desktop "Open Calculator"# drive this machine's desktop
holo --local"Summarize news.ycombinator.com"# run the agent loop on this machine
holo sessions watch <session-id> # follow a running session
holo mcp install # add the MCP server to your editor
Tasks run on h/web-surfer-flash unless you pass --agent or set a default with holo agents use. Run holo --help, or holo <command> --help, for every option.
~/.holo/agents.md joins the instructions of every agent holo runs, and ~/.holo/skills/<name>/SKILL.md joins its skills.
Interactive sessions
holo in a terminal opens a session you talk to in plain words. Each message continues the same session, with its browser and context, until you start fresh with /new.
Key
Action
type, then enter
message the agent while it works
esc
pause the agent; esc again resumes
/answer
ask the agent to answer now
/
list commands: /new, /retry, /resume, /agent, /live, /share, /status, /copy
?
all shortcuts
ctrl+c
cancel the turn; twice to exit
An agent that drives this desktop, like h/holo-desktop, uses your mouse and keyboard, so typing goes to your apps instead: press esc twice, from any app, to stop it.
let Cursor, Claude Code, Codex, and other MCP clients run agents through holo mcp; --remote adds the hosted server instead
holo local
serve a browser or desktop on this machine for a session started elsewhere
holo login, logout, whoami, doctor
manage and check your credentials and setup
Scripts and CI
Scripts never prompt. Set HAI_API_KEY, or pipe a key into holo login --key, then use --json for machine-readable output or -q for the answer alone:
bash
holo --json run "What's the top story on Hacker News?" | jq -r .answer
holo run -q "What's the top story on Hacker News?" > answer.txt
--json prints session_id, status, answer, outcome, error, error_code, and agent_view_url. The exit code is 0 when the session completes and 1 otherwise.
Credentials resolve from --api-key, then HAI_API_KEY, then ~/.config/hai/.env.
Python SDK guides
How a session works
A session is one run of an agent against a task. It moves through a small set of states: pending, running, and then a settled state such as completed, idle, failed, timed_out, or interrupted.
You drive a session two ways. run_session creates it and blocks until it settles, which suits one-shot tasks. start_session creates it and returns a handle right away, so you can read and steer the agent while it works.
python
session = client.start_session(
agent="h/web-surfer-pro",
messages="Find the top story on Hacker News",
)
print(session.id)
result = session.wait_for_completion()
print(result.status, result.answer)
Watch and steer a running session
A handle bound to the session id exposes the full lifecycle. Read the agent's progress at three levels of detail:
status() is a cheap snapshot with the state, step count, and token usage. changes(from_index=0) long-polls for new events and the final answer. get() returns the full Session resource.
While the session is not in a terminal state, you can intervene:
python
session.send_message({"type": "user_message", "message": "Only consider the last 24 hours"})
session.pause()
session.resume()
session.force_answer()
session.cancel()
send_message redirects the agent on its next step and wakes an idle session. pause halts with state preserved until resume. force_answer makes the agent stop exploring and answer from what it has. cancel ends the session as interrupted.
Multi-turn sessions
By default a session ends as soon as the agent answers. Set idle_timeout_s to keep it open: after each answer the session goes idle and waits that long for your next message, carrying its full context and browser state across turns.
python
session = client.start_session(
agent="h/web-surfer-pro",
idle_timeout_s=600,
messages="Find the top story on Hacker News",
)
first = session.wait_for_completion()
session.send_message({"type": "user_message", "message": "Now summarize its comments"})
second = session.wait_for_completion()
Structured output
Pass a pydantic model as answer_schema and the agent's final answer comes back as a validated instance. The model's JSON schema is sent as the agent's answer format; the raw wire value stays at result.final_changes.answer.
python
from pydantic import BaseModel
from hai_agents import Client
classJob(BaseModel):
title: str
company: strclassJobs(BaseModel):
jobs: list[Job]
client = Client()
result = client.run_session(
agent="h/web-surfer-pro",
messages="Find 3 open ML engineering roles in Paris.",
answer_schema=Jobs,
)
for job in result.answer.jobs:
print(job.title, "@", job.company)
A completed answer that does not match the schema raises AnswerValidationError, with the raw payload on .raw. Sessions that end without completing return their raw answer untouched.
Custom tools
Expose your own Python functions to the agent. Pass them to run_session and the polling loop runs each one when the agent calls it, then posts the result back so the session continues. Any function with typed parameters and a docstring works; the input schema is derived from the signature.
python
from hai_agents import Client
defget_weather(city: str) -> str:
"""Get the current weather for a city."""returnf"Sunny in {city}"
client = Client()
result = client.run_session(
agent="h/web-surfer-pro",
messages="What should I wear in Paris today?",
tools=[get_weather],
)
Use the @tool decorator to override the name or description:
python
from hai_agents import tool
@tool(name="lookup_order", description="Look up an order by its id.")deflookup(order_id: str) -> dict:
return {"id": order_id, "status": "shipped"}
A tool that raises is reported to the agent as a tool error rather than crashing the run. With AsyncClient, tools may be async def.
Prebuilt: one-time passwords (2FA)
hai_agents_tools ships ready-made tools. otp_tool lets the agent ask for a one-time password, verification code, or confirmation link when a login or signup step needs one. Without a handler it prompts on stdin; imap_otp_handler reads the code straight from a mailbox over IMAP (for Gmail, use an app password).
python
import os
from hai_agents import Client
from hai_agents_tools import imap_otp_handler, otp_tool
handler = imap_otp_handler(
host="imap.gmail.com",
username="agent-inbox@gmail.com",
password=os.environ["GMAIL_APP_PASSWORD"],
)
client = Client()
result = client.run_session(
agent="h/web-surfer-pro",
messages="Log in to example.com and check for new notifications",
tools=[otp_tool(handler)],
)
Like every custom tool, the handler runs entirely in your process: the IMAP credentials never leave your machine, and the agent only receives the single extracted code or link -- never mailbox contents.
Browser profiles and vaults
Start a session on a browser that already knows the user. A browser profile restores saved cookies and storage from an earlier session, and a vault lets the agent sign in to sites with secrets that never enter its context. Bind both through per-run overrides:
python
result = client.run_session(
agent="h/web-surfer-pro",
messages="Open my dashboard and report any new alerts",
overrides={
"agent.environments[kind=web].browser_profile_id": "<profile-id>",
"agent.environments[kind=web].vault_id": "<vault-id>",
},
)
Async
AsyncClient mirrors Client for asyncio. Every session method is a coroutine.
python
import asyncio
from hai_agents import AsyncClient
asyncdefmain():
client = AsyncClient()
result = await client.run_session(
agent="h/web-surfer-pro",
messages="What are the top 3 stories on Hacker News right now?",
)
print(result.answer)
asyncio.run(main())
Local agents
Client.local() and await AsyncClient.local() run the agent on this machine through a local agent runtime,
started on demand or passed in with runtime=.... A desktop is this machine; a browser picks host="user_device" or
host="cloud".
Client() keeps using the hosted Agents API. Closing the client stops a runtime it started, unless other clients still
have active sessions there.
python
from hai_agents import Client
with Client.local(local_options={"binary_path": "/path/to/hai-agent-runtime"}) as client:
session = client.sessions.create_session(
agent={
"name": "local-example",
"description": "Local desktop example",
"instructions": "Answer the user's task on this desktop.",
"environments": [{"id": "my-laptop", "kind": "desktop"}],
},
messages=[{"type": "user_message", "message": "Open the Calculator app."}],
max_steps=8,
max_time_s=120,
)
# Poll or steer the session here, before leaving the client context.
One agent drives this machine's desktop at a time: a second process asking for a desktop bridge fails fast instead of
sharing the mouse. holo local stop stops every local turn on the machine; so does a double Esc
once hai_agents_local.killswitch.arm_esc_listener() is armed (macOS, Windows, and X11 Linux).
Code on this machine
A desktop in shell mode gives the agent a shell on this machine. It runs commands, edits files and writes code in a
folder, and drives the screen from the same shell when a result only shows in a window.
bash
pip install "hai-agents[cli,workstation]"
python
from hai_agents import Client
Client().agents.create_agent(
name="laptop-coder",
description="Runs commands and edits files on my machine.",
environments=[{"id": "my-laptop", "kind": "desktop", "mode": {"type": "shell", "command_approval": "required"}}],
)
bash
cd ~/Projects/app
HAI_SHELL_WORKSPACE=. holo -a laptop-coder "Run the tests and fix the one that fails"
Without HAI_SHELL_WORKSPACE the agent works in a folder of its own, ~/hai/<session id>. With
command_approval: "required", holo asks before each command your allowlist does not cover: y runs it, a runs it
and always allows it, n refuses. From code, read result.pending_approvals and answer with session.approve(call_id)
or session.deny(call_id, message).
On macOS every command runs inside Anthropic's sandbox-runtime,
downloaded on the first session: it writes in the workspace only, reaches the Python and npm registries, and cannot
read your credentials. On Linux and Windows the sandbox is off until you install it. The
guide covers both.
Inspect and share sessions
List past sessions and create a public replay link:
python
page = client.sessions.list_sessions(size=10)
for summary in page.items:
print(summary.id, summary.status)
link = client.sessions.share_session("<session-id>")
print(link.share_url)
Regions and configuration
The client targets the EU region by default; pass environment to use the US region instead:
python
from hai_agents import Client, HaiAgentsEnvironment
client = Client(environment=HaiAgentsEnvironment.US)
Client also accepts a custom base_url, and an api_key when you do not want to use the environment variable:
from hai_agents import AnswerValidationError, UnprocessableEntityError
from hai_agents.core import ApiError
ApiError is the base for HTTP failures and carries .status_code and .body. UnprocessableEntityError is the 422 raised when a request fails validation. AnswerValidationError is raised when a completed answer does not match answer_schema, with the unparsed value on .raw.
Webhooks
Verify the signature on an incoming webhook before trusting it: