# WebMCP: Handing the Interface to an Agent in Your Browser An AI agent running in your browser can now use AgentRQ directly. Not by scraping the page, and not by being handed API credentials — by calling typed tools the page itself offers it. List your workspaces, open a task, reply in it, change a status, build a workflow: anything you can do by clicking, it can do by calling a tool. This shipped in [PR #452](https://github.com/agentrq/agentrq/pull/452), merge commit [`6faecfe`](https://github.com/agentrq/agentrq/commit/6faecfe7abdc31f1335a19efe35cce8edb94ca0c), tagged v0.5.8. It is 1,853 added lines and zero deleted ones — nothing about the existing app changed.  Every task on that board was created by a `createTask` tool call, and the browser was moved to that page by a `navigate` tool call. Nobody clicked anything. ## What WebMCP Actually Is [WebMCP](https://github.com/webmachinelearning/webmcp) is a browser API that lets a **page** hand a set of typed tools to an agent running in that same browser. AgentRQ already has an MCP server — that is the thing an external agent connects to over the network with a workspace token. WebMCP is the other direction: | | Existing MCP server | WebMCP | |---|---|---| | Who connects | An agent somewhere else, over the network | An agent in the tab you already have open | | Credential | A workspace token you issue and paste | None — your existing session cookie | | Setup | Configure a server URL and token | Sign in | | Scope | The workspace the token is for | Everything your account can see | Because the tools execute **inside the open tab**, there is no token to issue and no separate connection to configure. Open AgentRQ, sign in, and the tools are there. ## 52 Tools, Registered on Sign-In The catalogue lives in [`frontend/src/webmcp/tools.js`](https://github.com/agentrq/agentrq/blob/main/frontend/src/webmcp/tools.js) and registers 52 tools, grouped roughly as the app itself is: - **Workspaces** — list, read, create, update, archive, unarchive, delete, stats, Slack channel, connection token. - **Tasks** — list, read, create, reply, respond, status, assignee, order, move, stop, delete, permission verdicts, elicitation answers, scheduled-task template, counts. - **Events** — list, read, create, update, delete, their triggers, and the tasks an event spawned. - **Workflows** — list, read, create, update, delete, steps, tasks, and the whole-workflow-as-text editor.  That `webmcp-demo` workspace sitting alongside the real ones was created by a `createWorkspace` tool call — the same POST the **+ New** button makes. ## The Two Tools Only a Page Can Offer Fifty of the tools mirror an API function. Two do not, and they are the reason this is WebMCP rather than a published HTTP API: - **`getCurrentPage`** reports the route path and its params — where you are right now. It is what turns "reply to this task" into a real call, instead of the agent asking you to read an ID out of the address bar. - **`navigate`** moves you through the app via the SPA router, so the agent can take you to what it just did. An HTTP API cannot answer either question. It has no idea what you are looking at. ## What This Unlocks A page handing an agent its own tools is different in kind from publishing an API, and the difference is worth spelling out. **"This task" becomes a thing you can say.** An agent holding a workspace token has no referent for "this" — it sees a database, not a screen, so every instruction has to carry an ID you read out of the address bar first. `getCurrentPage` removes that step: "reply to this one and mark it blocked" resolves to the task in front of you. That sounds minor until you count how much of talking to an agent about your own tools is currently spent reciting identifiers at it. **Scope follows the person, not a token.** AgentRQ's MCP server is connected per workspace — the connection URL carries the workspace ID, and so does the token. That is the right shape for an agent that works **inside** one workspace. It is the wrong shape for a question about all of them. A browser agent inherits your session instead, so it sees exactly the workspaces you see, and "which of these has something stuck since yesterday" is one question rather than a token and a connection per workspace. **Setup was the thing standing in the way.** Most integrations that require issuing a credential and configuring an endpoint never get set up at all — not because they are hard, but because doing it is a small task that is always less urgent than the work it would help with. Here the setup is signing in, which you did anyway. The floor drops from "configure an integration" to "ask." **Supervising agents is itself work, and now it is delegable.** AgentRQ exists so a person stays in the loop while agents do the work. But being in the loop **is** work: triaging a board, answering permission prompts, moving a task filed in the wrong workspace, fixing the one step in a workflow that is wrong. That is precisely what the 52 tools cover — and it is the layer that grows fastest as you run more agents. The assistant already open in your browser can take it, without being handed anything you don't already have. **A credential you never have to manage.** A pasted token is a standing grant: it works from anywhere, it outlives the tab, and it stays valid until somebody remembers to revoke it. The WebMCP path issues nothing at all. The tools ride the cookie you are already using and are withdrawn the moment you sign out, so revocation is a thing people actually do rather than a thing they mean to get around to. **The agent's capabilities cannot drift from the product.** Because the catalogue mirrors `api.js` and a test enforces it, a tool exists for a capability the day the capability does. An agent working through WebMCP is never operating last quarter's API surface — which is the failure mode every hand-maintained integration reaches eventually. **And the work comes back where you can see it.** `navigate` means an agent can put the result on your screen instead of describing it in a transcript. You approve it, correct it, or take over on the board itself — which is the only place the state really lives. Human-in-the-loop stops meaning "read the agent's summary and trust it." ## Reads, Writes, and the Seven That Remove Things Every tool carries annotations so an agent can tell what it is about to do before it does it. In [`tools.js`](https://github.com/agentrq/agentrq/blob/main/frontend/src/webmcp/tools.js) the descriptor builder sets three of them: ```js annotations: { readOnlyHint: readOnly, // Both spellings: MCP annotates removal with `destructiveHint`, while the // WebMCP draft asks whether an action is consequential. Unknown members // are ignored, and being understood by both is worth more than guessing. destructiveHint: destructive, consequentialHint: !readOnly, }, ``` Read out of a live registration, that comes to **19 tools marked `readOnlyHint`** and **7 marked `destructiveHint`**: `deleteWorkspace`, `deleteTask`, `deleteEvent`, `deleteEventTrigger`, `deleteWorkflow`, `deleteWorkflowStep`, and `replaceWorkflowFromText` — the last one because it drops anything not present in the text you give it. Worth being precise about what those annotations are: they are **labels, not enforcement**. The tools exist, so an agent is technically capable of calling them, exactly as you are. Marking them is what lets a well-behaved agent confirm with you first. The page cannot make it. ## "Everything the UI Can Do" Is a Test, Not a Claim The interesting part is that the coverage claim is checkable. Every button in the AgentRQ frontend ultimately calls a function exported from `frontend/src/api.js`, so the rule the catalogue follows is that it mirrors that module function for function. [`frontend/test/webmcpTools.test.js`](https://github.com/agentrq/agentrq/blob/main/frontend/test/webmcpTools.test.js) imports every export of `api.js`, drives the whole catalogue against a recording stub, and asserts each API function was reached. It runs the catalogue twice — once with an input carrying every field any tool asks for, once empty — because tools like `listTasks` branch between a per-workspace and a global call, and one pass would leave a branch unvisited. Add a function to `api.js` without adding a tool, and the suite fails. That is the intent. Two exemptions are written into that test with their reasons: - **`recordTelemetry`** — instrumentation the app records about itself, not an action a person takes. - **`getAttachmentUrl`** — it builds a URL the page renders; the bytes are fetched by the browser with the session cookie, which an agent cannot replay outside the page. There is a further test guarding the exemption list itself: if one of those names disappears from `api.js`, it fails, so the list cannot silently stop meaning anything. ## The Security Shape Every tool call is the same HTTP request the interface itself makes, carrying the same session cookie. The agent inherits exactly your permissions — no more. If you cannot delete a workspace, neither can it. WebMCP issues no credential of its own. One nuance worth stating plainly: `getWorkspaceToken` is in the catalogue, because the interface shows you that token too. Its tool description says so outright — "This is a credential: show it to the user, never paste it into anything else." Registration is tied to the session, and that is a security property rather than tidiness. All 52 tools are registered against a single `AbortController`; signing out aborts it and withdraws them. This had to be explicit, because signing out does not reload the page — anything left registered would leave an agent acting in a session that had ended. In `App.vue` the withdrawal is the **first** statement in `logout()`, before the network call: ```js async function logout() { // Before anything else: these tools act as the signed-in user, and the page // is not reloaded on sign-out, so leaving them registered would leave an // agent holding the last person's session. webmcp?.unregister() webmcp = null await unsubscribePush() ... } ``` Driving a real signed-in AgentRQ instance and then clicking Logout takes the registered count from 52 to 0, with the page never reloading. ## Which Browsers WebMCP is new and support is uneven. AgentRQ checks both spellings the specification has used — `document.modelContext` first, then `navigator.modelContext`, which the [WebMCP guide](https://github.com/agentrq/agentrq/blob/main/docs/WEBMCP.md) notes is deprecated in Chromium 150. A browser with neither registers nothing and behaves exactly as before. The API also requires a secure context, so nothing appears on a plain `http://` page. Serve AgentRQ over HTTPS, or use `http://localhost`. The desktop app runs the same interface and needs no separate code path. The whole browser seam is one 90-line file, [`frontend/src/webmcp/modelContext.js`](https://github.com/agentrq/agentrq/blob/main/frontend/src/webmcp/modelContext.js), kept free of Vue. WebMCP is a W3C Community Group draft that has already moved once; isolating it is what makes the next move cheap. Tools are registered one at a time, so a schema a browser dislikes costs that one tool rather than the catalogue or the page. ## What This Does Not Do Being explicit, so nobody has to guess: - It **does not grant an agent any permission you lack**, and issues no token or credential of its own. - It **does not work in a browser without WebMCP**, or on a non-secure origin. Nothing registers and the app is otherwise unchanged. - It **does not expose attachments or telemetry recording** — the two exemptions documented in the parity test. - It **adds no new UI page, setting, CLI command, server-side MCP tool, or API endpoint**. It registers browser-side tools against the existing REST API. The whole PR touches 13 files, all of them frontend, desktop, or docs. - It **does not let an agent bypass the per-command permission prompts**. Answering one is itself a tool call — `sendPermissionVerdict` — made as you. ## Checking It Yourself The repository ships a verifier that drives the whole path in a real browser with no backend at all. It installs a stub `document.modelContext` exactly as a supporting browser would, answers the API itself so every tool call is observable, and checks registration, invocation, navigation, annotations, and withdrawal on sign-out: ``` $ cd desktop && npm run verify:webmcp ─── WebMCP, in a real browser ─── ✓ the app registers its catalogue with the browser — 52 tools ✓ including the tools only a page can offer — getCurrentPage/navigate present: true ✓ and the ones that mirror the interface — getCurrentPage, navigate, getCurrentUser, listWorkspaces, … ✓ invoking a tool drives the interface's own API — POST /api/v1/workspaces/ws1/tasks ✓ and the tool returns what the API said — {"id":"t9","title":"From an agent"} ✓ getCurrentPage answers with the live route — {"path":"/","params":{},"query":{}} ✓ the navigate tool moves the user — now at /events ✓ reads and deletions are annotated for the agent ✓ the Logout control was reachable — "clicked" ✓ signing out withdraws every tool — 0 tools left registered ✓ all checks passed ``` A note on the screenshots above: no shipping browser enables WebMCP by default yet, so they were captured against a local AgentRQ build with the same stub `document.modelContext` that verifier installs. The tool calls, the HTTP requests they made, and the interface reacting to them are all real; only the browser's half of the protocol is stood in for. Full documentation is in [`docs/WEBMCP.md`](https://github.com/agentrq/agentrq/blob/main/docs/WEBMCP.md). --- **AgentRQ is currently in public beta. Join our [GitHub community](https://github.com/agentrq/agentrq) to help shape the future of human-agent collaboration.**