pi-webmcp-guard

A security-first WebMCP client for the Pi coding agent.

Experimental: WebMCP and Chrome's implementation are still changing. This package currently targets Chromium browsers that expose the experimental CDP WebMCP domain.

Design principles

• Deny unknown web origins by default.
• Never inject page-provided tool descriptions into Pi's system prompt.
• In safe mode, require confirmation for every call; page-provided risk annotations are hints, not proof.
• Treat every page-provided description and result as untrusted content.
• Bind tools to their exact scheme, host, port, target, frame, and page epoch.
• Invalidate tools immediately when a page navigates or a target detaches.

Current commands

• /webmcp doctor
• /webmcp connect
• /webmcp tabs
• /webmcp inspect
• /webmcp auto on|off|status
• /webmcp trust <origin>
• /webmcp revoke <origin>
• /webmcp audit
• /webmcp disconnect

Agent tools

• webmcp_list_tools
• webmcp_invoke
• webmcp_cancel

The extension deliberately exposes a stable gateway instead of mounting every page-provided tool into Pi's top-level tool list.

Requirements

• Pi 0.84.4 or newer
• A Chromium browser with the experimental WebMCP implementation
• Chrome remote debugging enabled
• The WebMCP and DevTools WebMCP experimental flags enabled when required by the installed Chrome version

The CDP endpoint is loopback-only by default. Set PI_WEBMCP_CDP_ENDPOINT=http://127.0.0.1:<port> when Chrome is listening on a different local port. Remote CDP endpoints are intentionally rejected.

Local installation

pi install npm:pi-webmcp-guard

To work from source instead:

git clone https://github.com/keyuchen21/pi-webmcp-guard.git
cd pi-webmcp-guard
npm install
npm run check
pi install .

Then start Pi and run:

/webmcp doctor
/webmcp connect

connect asks the user to select exactly one Chrome tab and separately trust that tab's exact origin for the current Pi session. Trust is intentionally not persisted in the beta release.

Auto mode

For a fully hands-off session, run:

/webmcp auto on
/webmcp connect

Auto mode allows WebMCP tools from every HTTP(S) origin visited in the selected Chrome tab and runs calls without per-origin or per-call confirmation. It does not attach to other tabs. Navigation still invalidates old tool ids, inputs are still schema-validated, results remain bounded and labeled untrusted, and every call is still audited. Auto mode is off by default, lasts only for the current Pi process, and can be stopped immediately with /webmcp auto off.

Warning: a signed-in website can expose consequential tools. Auto mode lets Pi invoke them without asking you again. Use a dedicated browser profile and do not enable it around sensitive accounts unless you accept that risk.

Security behavior

• Unknown origins cannot expose callable tools.
• HTTP and HTTPS origins are distinct trust entries.
• Cross-origin navigation invalidates all old tool ids.
• Safe mode requires user confirmation for every call, including calls the page labels read-only. Explicitly enabled auto mode bypasses these confirmations.
• Inputs are validated against the page-advertised JSON Schema.
• Page results are labeled untrusted and limited to 12,000 characters.
• Pending calls are canceled on abort, timeout, navigation, detach, or shutdown.
• Up to 200 invocation audit records are retained in memory for the current Pi session and can be viewed with /webmcp audit.

Development

npm install
npm run check
pi -e ./src/index.ts

The repository also contains a self-contained WebMCP demo page. With a WebMCP-enabled Chrome listening on port 9223:

python3 -m http.server 8765 --directory demo
PI_WEBMCP_CDP_ENDPOINT=http://127.0.0.1:9223 \
  PI_WEBMCP_TARGET_MATCH=127.0.0.1:8765 \
  npm run demo:capture
npm run demo:video

The capture script discovers and invokes set_security_mode through Chrome's real CDP WebMCP domain. The video builder emits a 1280×720 H.264 MP4 suitable for the Pi package gallery.

Status

Version 0.1.0-beta.3 is published on npm. The beta implementation has been exercised against Google's WebMCP Travel demo and this repository's isolated demo page on Chrome 151.