Global WebMCP

Browser agents can discover how a website works. Making them rediscover the same workflow on every run is slow, expensive, and brittle.

Global WebMCP separates discovery from execution. Codex drives the website, measures the result, and writes a strict versioned action map. A local MCP server turns that map into a persistent function call.

A click trace is evidence, not an API. The map stores the narrowest stable interface the agent found.

See it work

Ask the catalog for a Wikipedia action:

{
  "tool": "find_sites",
  "arguments": {
    "query": "search Wikipedia"
  }
}

The catalog returns a versioned reference:

en.wikipedia.org/search_articles@1.1.0

Call it:

{
  "tool": "execute_site_action",
  "arguments": {
    "actionRef": "en.wikipedia.org/search_articles@1.1.0",
    "input": {
      "query": "web model context protocol"
    }
  }
}

The live verifier gets HTTP 200 and returns:

[
  "AT Protocol",
  "HTTP",
  "Communication protocol",
  "HTTPS"
]

Run the same proof yourself:

npm run verify:wikipedia

Related MCP server: Sophia Stack MCP

Install

Global WebMCP is a local stdio server. It needs Node.js 20.19 or newer.

git clone https://github.com/benjang032/globalwebmcp.git
cd globalwebmcp
npm install
npm run build

Add it to Codex from the repository root:

codex mcp add globalwebmcp -- node "$PWD/dist/src/index.js"

For another MCP client, configure the same process:

{
  "mcpServers": {
    "globalwebmcp": {
      "command": "node",
      "args": ["/absolute/path/to/globalwebmcp/dist/src/index.js"]
    }
  }
}

Teach it a site

The repository includes a project-local Codex skill. Run Codex from this checkout, then ask:

$map-site-action map article search on Wikipedia

The skill drives the browser itself. It checks for native WebMCP, a stable URL or form, accessible DOM, and relevant same-origin requests. It then writes the smallest binding that preserves the observed result.

When a replay fails, run the skill again. It reproduces the failure, repairs the binding, bumps the map version, and reruns the checks. Runtime execution does not guess when a site changes.

How it fits together

website
   │
   │ browser discovery
   ▼
map-site-action skill
   │
   │ writes a reviewed contract
   ▼
maps/<site>.json
   │
   │ strict startup validation
   ▼
local Global WebMCP server
   │
   ├── find_sites
   ├── list_site_actions
   ├── prepare_site_action
   └── execute_site_action

The number of MCP tools stays fixed as the catalog grows. Sites add data, not another server process or another tool namespace. Each map owns one site and a set of versioned actions. See the complete maps/wikipedia-en.json example.

What it will and will not run

The current executor is intentionally strict:

• The map fixes the URL. Callers cannot supply or override it.

• JSON Schema validates every input before rendering.

• Public actions use GET on the declared HTTPS origin.

• The server does not follow redirects.

• Requests time out after 15 seconds.

• Responses stop at 1 MiB.

• Map text and website output remain untrusted.

• The map format has no fields for credentials, cookies, tokens, or browser state.

This is the useful first cut. Browser-session execution and authenticated writes belong in later adapters because they need session ownership, approval, and stronger completion checks.

Top-site options

These options follow Similarweb's worldwide ranking for July 2026, updated August 1, 2026. Each site was inspected in a live browser before its map was written.

The catalog also includes executable Wikipedia and GitHub searches, a blocked GitHub issue action, and a blocked Amazon UK product search.

Travel search options

These actions preserve the full search intent without entering a property or reservation flow.

Develop

npm run typecheck
npm test
npm run maps:check
npm run verify:wikipedia

The test suite validates the protocol, catalog, strict input boundary, blocker policy, and MCP stdio flow. The Wikipedia check calls the real local MCP server and the live Wikipedia API.

globalwebmcp/
├── .agents/skills/       # autonomous website mapper
├── maps/                 # versioned site contracts
├── src/protocol.ts       # map schema and safety rules
├── src/catalog.ts        # immutable action index and planner
├── src/executor.ts       # bounded public HTTP execution
├── src/server.ts         # four MCP tools over stdio
├── scripts/              # map and live verification
└── tests/                # protocol, catalog, and MCP checks

The design record lives in docs/design/0001-v0-catalog.md.

License

MIT. Build the browser bridge only when a real site forces you to.