Skip to main content
Glama

tab-mcp

Connect your AI app to a web page open in a browser tab.

A web page offers some of its functions as MCP tools. The page connects to a tab-mcp relay and gets an address. You add the address to your AI app (Claude, ChatGPT, Claude Code, Codex; see compatibility for which apps work) and type a code that the page shows. The AI app then calls the page's tools through the relay while the tab stays open. Nothing has to be installed on your computer.

The page does this with the tab-mcp client library. A page that offers its tools only with the browser's WebMCP reaches an AI app through the extension tab-mcp for Chrome: How the parts fit together.

The diagram editor is connected to Claude Desktop with its address and the code it shows; Claude then lists the page's tools and calls them

The demo: the diagram editor connected to Claude Desktop, then Claude calling the page's tools (45 s; waiting cut, Claude's work sped up).

How the parts fit together

Two paths lead through the tab-mcp relay to AI apps. A page with tab-mcp-client, in any browser with nothing for the user to install, connects to the relay with a WebSocket. A page with WebMCP tools, in Chrome with WebMCP on and the tab-mcp extension installed, is read by tab-mcp for Chrome, which connects to the relay with a WebSocket. The AI apps reach the relay over MCP.

tab-mcp has three parts:

  • The relay (@ractive-ch/tab-mcp) is a server in the middle. An AI app adds it as a remote MCP server: an address, then a pairing code. Pages and the extension connect to it with a WebSocket. It passes requests on and knows no tools. A site runs its own relay; the hosted one, tab-mcp.ractive.ch, is for ractive.ch's examples and the extension's default.

  • The client library (@ractive-ch/tab-mcp-client) is for site owners. The site builds it into a page and registers tools with it. The page then connects to the relay itself.

  • tab-mcp for Chrome (packages/tab-mcp-extension) is a browser extension for users. It reads the WebMCP tools of the page in front and offers them to the AI app through the relay.

WebMCP is the browser's own way for a page to offer tools (document.modelContext.registerTool()), a draft of the W3C Web Machine Learning Community Group (explainer). Its tools reach only agents inside the browser, and only where the browser has WebMCP turned on. Chrome has it for sites in its origin trial and behind a flag (chrome://flags/#enable-webmcp-testing), Edge for sites in its own origin trial; Firefox and Safari do not have it.

A page's tools reach an AI app outside the browser on one of two paths. Which one depends on how the page offers its tools:

Page with the client library

Page with WebMCP tools only

The site

builds in @ractive-ch/tab-mcp-client and has a relay that allows its origin

calls document.modelContext.registerTool() and takes part in Chrome's WebMCP origin trial (or its users turn on the flag); needs nothing of tab-mcp

The user needs

any browser (Chrome, Edge, Firefox, Safari), and installs nothing

Chrome with WebMCP on, and the tab-mcp extension (tab-mcp for Chrome) installed: in review for the Chrome Web Store, until then loaded unpacked

The user connects

in the page: "Connect your AI app" shows the address and the code

in the extension's side panel, once: one address for whatever page is in front

The user is asked

by the page, before a tool the site marked as consequential

by the extension, before a tool the page did not mark read-only, and before its navigation tools take the tab to another site

If you run a site, the client library reaches the most users: it works in every current browser and your users install nothing. You run a relay for it (Self-hosting). With WebMCP tools only, you run nothing, but your tools reach AI apps outside the browser only for users of Chrome who have WebMCP on and the tab-mcp extension installed. You can do both: new TabMcp({ ..., webmcp: true }) also registers the library's tools with WebMCP. The diagram editor does, so it works on both paths.

If you use a site, look for "Connect your AI app" in the page: that page has the client library and you need nothing else. On a page without it, tab-mcp for Chrome offers your AI app the page's WebMCP tools, if the page has any. It reads a tab only after you click its icon there, or after you give it access to all sites. The extension also has tools of its own, which work on pages without tools too: page_info says which page is in front, and navigate, go_back, go_forward and reload move the tab.

The extension reads only WebMCP tools. A page that offers its tools with the client library alone, without webmcp: true, has none for it. There is no extension for Firefox or Safari; pages reach those browsers with the client library.

Related MCP server: @teatak/mcp-server-browser

Live examples

Try it without installing anything. These pages connect to the hosted relay tab-mcp.ractive.ch (overview: https://ractive.ch/tab-mcp/):

Page

What your AI app can do there

Diagram editor

draw, read and rearrange a diagram of boxes and arrows with you, and get it as a picture

Todo (React)

list, add, complete and delete todos in a React single-page app (deleting asks you in the page first); based on examples/react-todo

saturnus

use an HP 48 calculator emulator

Sign-in example

read, add and delete notes; the AI app connects by signing in with the same Google account as the page, without a code (identity binding)

The hosted relay is run for ractive.ch's examples, not as a service for other pages. It refuses every origin it does not list, and the page then shows "Could not connect to the relay (refused, unreachable, or this page's origin is not allowed)." For your own page, run your own relay, as in Quick start for page authors for development and Self-hosting for production.

How it works

sequenceDiagram
    actor You
    participant Page as Web page in your tab<br/>(tab-mcp-client)
    participant Relay as tab-mcp relay
    participant App as AI app<br/>(Claude, ChatGPT, Claude Code)

    Note over You,App: 1. Connect the page
    You->>Page: click "Connect your AI app"
    Page->>Relay: WebSocket /tab (tab-mcp.v1)
    Relay-->>Page: address /a/{id}/mcp and a 6-digit code
    Page-->>You: show the address and the code

    Note over You,App: 2-3. Pair the AI app
    You->>App: add the address
    App->>You: open the relay's /authorize page in your browser
    You->>Relay: check the AI app and the page, type the code
    Relay-->>App: token for this address
    Relay-->>Page: grant.added
    Page-->>You: list the AI app as connected, with Disconnect

    Note over You,App: 4. Call a tool
    App->>Relay: POST /a/{id}/mcp with the token: tools/call
    Note over Relay: checks the token and limits, knows no tools, stores no arguments
    Relay->>Page: http.request over the WebSocket
    opt the tool cannot be undone in the page
        Page->>You: ask first
        You-->>Page: allow
    end
    Page-->>Relay: the tool's result, streamed over the WebSocket
    Relay-->>App: the result

    Note over You,App: 5. Close the tab
    You->>Page: close the tab
    Page--xRelay: WebSocket closed
    App->>Relay: tools/call with the token
    Relay-->>App: "The page is not open" (the AI app stays paired)
  1. You click "Connect your AI app" in the page. The page opens a WebSocket to the relay and shows an address and a 6-digit code.

  2. You add the address to your AI app. The AI app opens the relay's sign-in page in your browser. It names the AI app and the page; you type the code.

  3. The AI app gets a token for that address. The page lists it as connected, with a Disconnect button.

  4. When the AI app calls a tool, the relay forwards the request to the page. The page runs the tool and answers. Tools whose effect you cannot undo in the page (deleting for good, sending, buying) ask you in the page first.

  5. When you close the tab, the tools are gone. The AI app stays paired and can use the tools again the next time you connect the page.

The relay sees tool arguments and results but does not log or store them. It stores only hashes of tokens. More in the threat model.

When to use something else

tab-mcp is for state that lives only in the browser (a drawing, an emulator, a form being filled in), and for acting as the signed-in user in their open tab. If a page's state lives on its server, an MCP server on that backend is the better answer: it works while no tab is open, needs no relay in between, and can check who calls with the site's own accounts. If the agent runs in the browser itself, it calls the tools a page registers with WebMCP without a relay.

Quick start for users

You need a page that offers tab-mcp, such as the live diagram editor.

  1. In the page, click "Connect your AI app" and copy the address.

  2. Add it to your AI app:

    • Claude Code: claude mcp add --transport http diagram <address>, then run /mcp in Claude Code and choose Authenticate.

    • Claude (claude.ai and the desktop app): Settings → Connectors → Add custom connector, then paste the address.

    • ChatGPT: on chatgpt.com, open Plugins and add an MCP server with the address.

    Step by step for each app, and what to do when it fails: connecting an AI app.

  3. Your browser opens the relay's page "Connect … from …". Check the AI app and the page's address, then type the code shown in the page.

  4. Ask your AI app to use the page. To stop, click Disconnect in the page, or close the tab.

claude.ai, Claude Desktop and ChatGPT on the web connect from their own servers, so they need a relay with a public HTTPS address. All three work; see compatibility.

Connecting an AI app to a page means trusting that page. The page decides what its tools do and how they are described. Connect only pages you trust, and type a code only for an AI app you started yourself. See SECURITY.md.

Quick start for page authors

  1. Run a relay that allows your page's origin. For local development with Docker:

    docker run --rm -p 8080:8080 \
      -e NODE_ENV=development \
      -e TAB_MCP_PUBLIC_URL=http://localhost:8080 \
      -e TAB_MCP_ALLOWED_ORIGINS=http://localhost:3000 \
      -e TAB_MCP_STORE=memory \
      ractive/tab-mcp:0.11.0
  2. Install the browser library:

    npm install @ractive-ch/tab-mcp-client
  3. Register tools and add a button:

    import { TabMcp } from "@ractive-ch/tab-mcp-client";
    
    const mcp = new TabMcp({
      relay: "http://localhost:8080",
      server: { name: "notes", version: "1.0.0" },
      appName: "notes",
    });
    
    await mcp.registerTool<{ text: string }>({
      name: "add_note",
      title: "Add a note",
      description: "Add a note (at most 500 characters) to the list on the page and return its id.",
      inputSchema: {
        type: "object",
        properties: { text: { type: "string", minLength: 1, maxLength: 500 } },
        required: ["text"],
        additionalProperties: false,
      },
      execute: ({ text }) => addNote(text),
    });
    
    connectButton.addEventListener("click", () => mcp.showConnectDialog());
  4. Open your page on http://localhost:3000, click the button and connect an AI app.

A Chrome or Edge extension can offer tools the same way, from its service worker or one of its own pages (such as its side panel); the relay's heartbeat keeps a service worker alive while it is connected (Chrome 116+, with the heartbeat under 30 s). In a service worker, pass storage and onConfirm: it has no localStorage and no document (see browser extensions). The relay then lists chrome-extension://<id>.

Mark tools whose effect the user cannot undo in the page, or that act outside it (delete for good, send, buy, change data on the server), with annotations: { consequentialHint: true }: the page then asks the user before each call ("Allow until reload" only if the page turns on alwaysAllow). A change the user sees and can take back in the page, such as add_note above, needs no question.

A site with its own AI assistant on the page can serve the tools to it over a MessagePort with mcp.serve(port, { client }), without a relay, pairing or an address; calls then come with client.kind === "local", and serve's onConfirm asks for them in the site's own chat. See Your own assistant on the page.

new TabMcp({ ..., webmcp: true }) also registers the tools with the browser's WebMCP where the browser has it, so that agents in the browser call them without pairing, with the same argument check and confirmation. Consequential tools (consequentialHint or destructiveHint) go there only when their registration lists "webmcp" in callers, which says per tool which callers see it. See WebMCP in the client README.

The client README covers the whole API; the live examples show what pages can offer.

There is no public relay for other sites: run your own (Self-hosting).

Agent skill

The repository has an Agent Skill that teaches a coding agent to add tab-mcp to a web app. In Claude Code:

/plugin marketplace add ractive/tab-mcp
/plugin install tab-mcp@tab-mcp

For Codex and claude.ai, see the plugin README.

Identity binding

For pages where users sign in, a relay can pair by identity instead of a code: an AI app connects only if the person signing in to the connection is the person signed in to the page, at the same OpenID Connect provider (Google, Keycloak, Auth0, Okta, Entra ID, your own). Your backend signs a short assertion for the page's user, and logging out of the page ends the AI connection at once. Set TAB_MCP_IDENTITY=oidc; the configuration and the client README show how.

Self-hosting

The relay is one process with a SQLite file. Run it with Docker:

docker run -d --name tab-mcp -p 127.0.0.1:8080:8080 -v tab-mcp-data:/data \
  -e TAB_MCP_PUBLIC_URL=https://relay.example.com \
  -e TAB_MCP_ALLOWED_ORIGINS=https://app.example.com \
  ractive/tab-mcp:0.11.0

Put it behind a reverse proxy or CDN with TLS, and run exactly one instance. Self-hosting explains the data volume, WebSockets, event streams and proxy time limits, health checks, backups and upgrades, with a privacy notice template for your users; configuration lists every setting and why the defaults are safe. The relay also runs without Docker on Bun (bun add --global @ractive-ch/tab-mcp, then tab-mcp).

Your own store. The relay keeps grants and token hashes (never tokens) in SQLite by default, or in memory. Embed it in your own Bun program with createRelay() and it takes any object that implements the TokenStore interface: PostgreSQL, Redis, Prisma or whatever your stack already runs. The package ships a conformance suite to check your store; token store has the interface, the guarantees a store must give and an example. A shared store does not let several relays serve one address: tab sessions live in the relay's memory, so each address still needs exactly one process.

Packages

Path

Published as

What

packages/tab-mcp

npm @ractive-ch/tab-mcp, Docker ractive/tab-mcp and ghcr.io/ractive/tab-mcp

the relay (README)

packages/tab-mcp-client

npm @ractive-ch/tab-mcp-client

the browser library a page uses (README)

packages/tab-mcp-extension

"tab-mcp for Chrome" 0.1.0 (in review for the Chrome Web Store; until then, load it unpacked)

the Chrome extension that offers the WebMCP tools of the page in front to an AI app (README)

examples/react-todo

–

a React todo app with the React bindings, live at https://ractive.ch/tab-mcp/examples/todo/ (README)

test/e2e

–

the end-to-end test: a relay, a test page in headless Chrome and an AI app's OAuth client (README)

plugins/tab-mcp

–

the agent skill and its plugin manifests (README)

Documentation

Status

0.16.2. Until 1.0, a new minor version can still change settings, the protocol or the API; the changelogs say what changed.

  • Released: relay @ractive-ch/tab-mcp 0.11.0 (npm and Docker) and browser library @ractive-ch/tab-mcp-client 0.16.2, on the npm tag latest.

  • tab-mcp for Chrome 0.1.0 is in review for the Chrome Web Store (submitted 2026-11-16); until then, load it unpacked (README). An unpacked build has the store's id, which the hosted relay allows.

  • tab-mcp speaks only MCP revision 2026-07-28 and accepts only AI apps that register through OAuth Client ID Metadata Documents. Claude Code, claude.ai, Claude Desktop, ChatGPT (web and Mac) and Codex work (Codex and ChatGPT for Mac with the mcp_2026_07_28 feature turned on); VS Code, Cursor and Gemini CLI cannot connect yet. Details in compatibility.

Development

Requires Bun 1.4.4 or newer.

bun install
bun run verify     # Biome, type check, tests, MCP conformance suite
bun run conformance  # only the official MCP conformance suite (relay and library)
bun run fix        # format and apply safe lint fixes

Licence

MIT, see LICENSE and AI_NOTICE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP bridge server that allows AI tools to call functions and execute code directly within a web browser tab. It enables developers to register custom browser-side tools with full access to the DOM, web APIs, and local application state.
      9 npm
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that runs in the browser, letting web pages register custom tools and prompts and expose them to an MCP client over WebSocket. Enables agents to drive UI, call page-scoped APIs, and get human-in-the-loop confirmation.
      10 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables websites to expose JavaScript functions as MCP tools, allowing AI agents to interact with the browser environment via a protocol and Chrome extension.
      1,110
      AGPL 3.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables browser-based AI chat interfaces to use local MCP tools by injecting a tool-call protocol into the page and executing approved filesystem, shell, and downstream MCP tool calls from a local daemon.
      560 npm
      AGPL 3.0