7.3 KiB
Outside agents
Agents that Hanzo Dev did not start can work with an environment through its MCP server. They can read projects and threads, start and message threads, and check which providers and models are available. This covers Claude Code or Codex in your own terminal, ChatGPT, and bots that support MCP. Each agent signs in once, and you choose what it may do.
Add Hanzo Dev to an assistant app
Open the command palette (Cmd/Ctrl+K) and choose Use Hanzo Dev in another
app (MCP), or use the button in Settings → Sharing & access. Pick the
app and follow the step for that app. Assistants like
Poke and Claude run in the cloud, so the wizard first asks you to sign in to Hanzo
Connect and turn it on for the environment. To reach your other machines through
the same connection, turn on Linked environments in Labs and
link them.
When the app opens the sign-in page, choose what it may do and approve with your Hanzo Connect account. On an older environment, the wizard asks for the level and gives you a code to paste instead. A code works once, for 5 minutes, and approves only that level.
For an app that is not listed, choose Something else…, add a remote MCP server with OAuth in that app, and paste the URL. Apps that require their own client ID cannot connect.
Get the MCP URL
In Settings → Environments, open a saved environment's menu and choose
Copy MCP URL. The URL is the environment's address followed by /mcp, for
example:
https://<environment-address>/mcp
When Hanzo Connect serves the environment, the copied URL is its Hanzo Connect address, which agents can reach from anywhere. Otherwise it uses the route this device is connected over, so an agent on the same device can reach it.
- An agent on your own computers can use
localhoston the host, Hanzo Connect, or anyhttpsaddress, such as Tailscale HTTPS. Signing in sends the agent's credentials to the environment, and agents only do that overhttpsor tolocalhost. A plain-httpLAN or Tailscale address, likehttp://100.x.y.z:3773, lets an agent find the environment but not finish signing in. - A hosted agent, such as ChatGPT or a bot running in the cloud, must reach the environment from the internet. Use the Hanzo Connect address. A Tailscale address only works from your own tailnet.
Approve a sign-in
The first time an agent connects, it opens a sign-in page. When the agent reaches the environment through Hanzo Connect, the page opens on the Hanzo Dev web app: sign in with the Hanzo Connect account the environment is linked to and approve there, without a code. Otherwise the page opens on the environment. Either page names the agent and where its access goes:
- For an agent on your computer, approval returns to a
localhostaddress on the computer that opened the page. - For a hosted agent, approval goes to that service, such as
chatgpt.com. Anyone who runs that service gets the access.
Only approve a sign-in you just started. On the environment's own page, enter a
code from Use Hanzo Dev in another app (MCP), Settings → Sharing & access,
or hanzo auth pairing create on the host. A browser already signed in to the
environment with permission to manage access can approve without a code. On the
web app, Use a sign-in code instead opens the environment's own page.
A code from Use Hanzo Dev in another app (MCP) already carries the level you picked there. With another code, choose what the agent may do here: Auto is selected by default, or the closest lower mode allowed by your organization’s policy. Approving without a code starts at Read only:
- Read only lets the agent read projects and threads and see the available providers and models. It cannot change anything.
- Supervised through Full access also let it start, message and stop threads in every project. A thread it starts or steers cannot run with more permissions than the mode you chose.
What outside agents can call
Some tools only work for an agent running inside a Hanzo thread, because they act as that thread: subagents, secret requests, rendered HTML, the browser preview, devices, and worktree handoff. They still appear in an outside agent's tool list, but calling one returns an error saying it needs an agent running inside Hanzo Dev.
- To hand off work, start a thread with
hanzo_thread_launch, then follow it withhanzo_thread_waitorhanzo_thread_read, instead ofcreate_threadsordelegate_task. - Tools that default to the caller's own project or thread need an explicit
projectIdorthreadId. - To list threads across projects, call
hanzo_thread_listwithallProjects: true, or usehanzo_thread_search.
Claude Code
claude mcp add --transport http hanzo https://<environment-address>/mcp
claude mcp login hanzo
claude mcp login opens the sign-in page in your browser. On a machine
without a browser, add --no-browser, open the printed URL elsewhere, and
paste the final URL back when asked. claude mcp list shows hanzo as connected
once you approve.
Codex
codex mcp add hanzo --url https://<environment-address>/mcp
codex mcp login hanzo
codex mcp login --no-browser prints the sign-in URL instead of opening it.
codex mcp list shows hanzo with OAuth once you approve.
ChatGPT
Add the environment as a custom MCP app in ChatGPT's apps settings:
- Create a new app or plugin with a custom MCP server.
- Set the server URL to
https://<environment-address>/mcp, using the Hanzo Connect address. - Choose OAuth for authentication. ChatGPT discovers the rest; you do not need a client ID or secret.
- Create the app, then approve the sign-in page that opens.
Other agents and bots
Any agent that supports remote MCP servers over HTTP with OAuth can connect. Give it the MCP URL and choose OAuth, and the agent finds the sign-in settings itself. Agents without OAuth support cannot connect.
Scripts on the host
On the machine that runs the environment, hanzo thread uses the same tools
without a sign-in:
id=$(hanzo thread start . "Find why the tests are slow")
hanzo thread send "$id" "Now fix it" --wait
hanzo thread show "$id"
hanzo thread list
. means the project that contains the current folder, or a git worktree of
its repository; a project id also works. A new thread uses the project's
default model and permission mode, and runs in the project folder unless you
pass --worktree <base-branch>. send never interrupts: a busy thread gets
the message as its next turn. Pass - as the message to read it from stdin.
To choose the model, pass --provider <instance-id> --model <slug>. Add
--option id=value for each model option, such as --option effort=high.
Option ids and values depend on the model; true and false set on/off
options.
--wait prints the agent's reply. It exits 1 when the run fails or stops, and
2 when the agent waits for an answer you give in the app. Add --json for a
result that always includes the thread id.
Remove an agent
Approved agents appear under Settings → Sharing & access like other clients. Revoke one there to cut off its access immediately. A sign-in lasts 30 days; after that the agent asks you to approve it again.