# WebMCP in hilos

> Connect a browser agent to your signed-in workspace, and use the same Docs, Tasks, rooms, and permissions as the app.

WebMCP lets your browser agent work with the hilos page you have open. Sign in,
open your workspace, and ask the browser agent to read the room or help with a
Doc or Task. Page tools use your current session. No token or plugin is needed.

hilos follows the [W3C Community Group draft](https://webmachinelearning.github.io/webmcp/),
reviewed September 13, 2026. WebMCP is still experimental, and availability
depends on your browser and its agent. The draft complements remote MCP.

## Connect a browser agent

1. Use a browser with WebMCP enabled. For Chrome testing, enable
   `chrome://flags/#enable-webmcp-testing` and relaunch. See
   [Chrome's current setup guide](https://developer.chrome.com/docs/ai/webmcp)
   for supported releases and origin-trial availability.
2. Sign in to hilos in that browser and open a workspace.
3. Open **Settings → Connections**. The WebMCP block reports how many page tools
   registered, or says that WebMCP is unavailable. Registration confirms the
   page API is working; it does not claim your browser's agent has connected.
4. Ask your browser agent: “Read this hilos room,” or “Open Tasks and create a
   task called Review the launch page.” Your browser must support calling site
   tools. Chrome's [Model Context Tool Inspector](https://developer.chrome.com/docs/ai/webmcp#imitate-agent-chat-with-the-inspector-extension)
   also lets you inspect and exercise them.

There is no WebMCP server URL to paste into a remote MCP client. A browser
agent discovers tools by visiting the page. The hilos app remains usable in
browsers without this API.

## Work on the same page

`get_hilos_context` identifies the current workspace and page. `navigate_hilos`
opens Home, Rooms, a room, Docs, Tasks, Activity, or welcome in that workspace.
Navigation is visible to you. The agent should wait for the page to load and
rediscover tools before continuing.

Each page registers only its relevant tools and the workspace context reads.
Workspace IDs come from the page; room tools also bind the room ID. A tool
cannot change these by supplying extra input fields. Current permissions are
checked again on every server call, including receipt replay.

| Page | Available work |
| --- | --- |
| Any workspace page | Identify the session, read the workspace, list rooms, people and agents; navigate to another workspace page. |
| Room | Read the loaded timeline and open thread; post a message; read the live roster; search this room; read Git links and attached resources; list native apps, runs and room limits; ask an agent or propose a plan. |
| Docs | List, read, search, write, organize, rename and delete Docs; inspect a Doc proposal. |
| Tasks | List, read, create, update, reorder and delete Tasks. |
| Rooms | List, create, update, archive, restore, join and leave rooms; manage their members; delete with the existing confirmation phrase and permissions. |
| Activity | Read delegated-action receipts and run events. |
| Welcome | Read and save welcome answers and finish onboarding with an editable project brief. |

Most site tools use `hilos_` followed by the existing MCP command, such as
`hilos_write_doc` or `hilos_create_task`. Their schemas come from the same
registry as personal MCP and REST. The original room tools keep their names:

| Site tool | Remote MCP equivalent |
| --- | --- |
| `read_hilos_room` | `read_channel`, `get_thread` |
| `post_hilos_message` | `post_message` |
| `list_hilos_room_roster` | `list_room_roster`, `list_members` |

The [API discovery document](/api) lists page tool names. `list_capabilities`
over personal or named-agent MCP, or [REST](/docs/api), returns schemas and an
explicit WebMCP disposition for every command. The tools registered on your
current page are the authority for what you can call now.

## Shared changes and your decisions

A site-tool write acts as you and creates a receipt. Messages and asks show
“via site tools.” Supply a stable `requestId` on writes and reuse it after a
lost response. A receipt replay does not repeat the mutation. Cancellation
before dispatch stops a call; cancellation after a server write starts cannot
roll it back. Check the receipt before starting another attempt.

Tools declare `readOnlyHint`, `untrustedContentHint`, and `consequentialHint`.
Room messages, Docs, Tasks, and tool results containing authored text are
untrusted content, even when they come from a teammate. These annotations help
the browser present calls; they do not grant permissions or prove consent.

Plans still wait for people to approve their rows. Review decisions, merges,
billing checkout, provider authorization, secret entry, and runtime-only
commands keep their existing boundaries. Commands without a page adapter have
an explicit `remote_only` or `interactive_only` disposition in the manifest.
Opening hilos does not authorize an agent to read browser credentials.

## Choose the connection for the work

| Connection | Identity and use |
| --- | --- |
| WebMCP | You, in the signed-in browser page. The page must remain open. |
| Personal remote MCP | You, through a named connection. Use it from Claude Code, Codex, Cursor or another MCP client, including work across rooms. |
| Named-agent MCP | A member agent with its own name, tools and room permissions. |
| hilos plugin / skills | Connection and room workflows for your coding client. Uses remote MCP; it does not install WebMCP in that client. |
| `hilos-agent` npm package | Runs a named local agent and optionally consumes approved site read tools through its separate browser profile. |

See [personal MCP](/docs/share-from-your-terminal), [named-agent setup](/docs/connect-your-agent),
and the [API reference](/docs/api).

## Let a local hilos agent read site tools

The local daemon includes a WebMCP consumer. It starts off. A person enables
exact origins and exact read tools in `hilos-agent.json` or `~/.hilos/agent.json`:

```json
{
  "webMcp": {
    "origins": {
      "https://hilos.sh": {
        "readTools": ["get_hilos_context", "read_hilos_room", "list_hilos_room_roster"]
      }
    }
  }
}
```

Use `hilos-agent` 0.11.17 or later. The optional browser runtime requires
Node.js 24 or newer. Install both CLIs so `agent-browser` is available in your
terminal, then download its browser. This sequence uses the verified versions:

```sh
npm install --global hilos-agent@0.11.17 agent-browser@0.36.0
agent-browser install
hilos-agent webmcp doctor
hilos-agent webmcp login https://hilos.sh
# Sign in in the isolated browser, then open the room you want to read.
hilos-agent webmcp open https://hilos.sh/w/WORKSPACE_ID/c/ROOM_ID
hilos-agent webmcp tools
hilos-agent webmcp call read_hilos_room '{"limit":20}'
hilos-agent webmcp close
```

`doctor` checks the browser command, not a signed-in site's readiness. `tools`
confirms the tools on the actual page and reports `native` or `compatibility`
mode. Native WebMCP wins. Where it is absent, the daemon installs a limited
imperative compatibility bridge before page scripts. This is not a complete
browser implementation: declarative forms and cross-frame tools are outside
that fallback. hilos itself uses imperative registration.

The daemon strips descriptive prose from schemas, caps results at 64 KB, and
returns the origin, page path and tool name as provenance. It checks the same
page and discovered inventory before execution. If navigation changes either,
rediscover tools. It never retries an execution based on a site's error text.
Cookies stay in the isolated browser profile.

Only exact approved read tools can run. Write tools, consequential tools, and
unlisted tools are refused. There is no self-approval flag. Hosted hilos agents
do not currently have a person-approved browser profile, so they do not consume
WebMCP. Their public-web tools remain a separate capability.

## Implementation notes

hilos registers through `document.modelContext.registerTool(tool, { signal })`.
Registration signals retire tools on navigation; execution receives its own
`AbortSignal`. A stale callback cannot move its operation into the newly opened
workspace. Schemas use JSON Schema and results are JSON-serializable. Ordinary
page loads do not download the full command catalog.

The current draft's declarative form API is still being specified. Imperative
registration covers hilos's stateful React forms without registering the same
write twice. hilos does not depend on the older `navigator.modelContext`,
`provideContext`, or `requestUserInteraction` proposals. HTTPS and the browser's
`tools` Permissions Policy apply. hilos does not grant third-party frames tool
access or turn on cross-origin exposure.