Turn any static site into an MCP server—without a backend.

MCP Pages standardizes client-side WebMCP tools for GitHub Pages and static sites. ai-proxy is the zero-dependency local relay that connects your browser tab to Claude Code and MCP clients over loopback HTTP.

Open Dashboard Read Specification Inspect This Site’s MCP Page

Quick Start Commands

Zero npm dependencies

Copy and run these commands in your terminal. Every URL below is rewritten at runtime to match this deployment:

# 1. Start the local ai-proxy relay (listens on 127.0.0.1:8788)
npx ai-proxy serve

# 2. Register and allow this site's MCP page in Claude Code
npx ai-proxy add https://<host>/<org>/<repo>/mcp --name ai-proxy

# 3. Open the authenticated local management dashboard
npx ai-proxy open dashboard

Building your own MCP Page on GitHub Pages? Vendor the zero-dependency browser library and verify your site:

npx ai-proxy vendor --out ./vendor/ai-proxy-web
npx ai-proxy doctor --dir .

ai-proxy Management Dashboard

Open Fullscreen Dashboard

Probing local ai-proxy relay...

How MCP Pages Works

Static hosts like GitHub Pages serve HTML, CSS, and ES modules—they cannot run persistent server processes. MCP Pages flips the transport direction: the page runs inside the user’s real browser tab, registers tools via navigator.modelContext, and connects outbound to the user’s local ai-proxy on 127.0.0.1:8788.

sequenceDiagram participant CC as Claude Code / MCP Client participant Relay as Local ai-proxy (127.0.0.1:8788) participant Tab as Browser Tab (mcp.html) CC->>Relay: POST /mcp?url=https://.../mcp.html (tools/call) alt Tab not connected (Idle Wake-up) Relay->>Tab: Open tab with fragment mcp-key=...&mcp-port=8788 Tab->>Tab: Move mcp-key to history.state & scrub URL bar Tab->>Relay: POST /tab/v1/hello (Bearer pageKey, tools[]) end Tab->>Relay: GET /tab/v1/poll?sessionId=sid Relay-->>Tab: 200 OK { callId, rpc } Tab->>Relay: POST /tab/v1/ack { sessionId, callId } Tab->>Relay: POST /tab/v1/reply { sessionId, callId, response } Relay-->>CC: JSON-RPC 2.0 Response { id: 1, result }

Seven Security Baselines for Shared Origins

All project sites under https://<user>.github.io/<repo>/ share a single browser Origin. A naive localhost bridge that trusts Origin: https://<user>.github.io or stores secrets in localStorage would let any repository on that host hijack your relay. ai-proxy enforces seven mandatory baselines:

Rule	Threat Mitigated	Normative Mechanism
`Rule 1`	Shared-Origin Neighbor Attack	Path-boundary URL prefix allowlist (`https://u.github.io/a/` never matches `/a-evil/`).
`Rule 2`	Same-Origin Storage Leakage	Per-page random key passed via URL fragment (`#mcp-key=`), moved immediately into tab-scoped `history.state`, and scrubbed via `history.replaceState`.
`Rule 3`	Cross-Site Request Forgery on `/mcp`	`POST /mcp` rejects any request carrying a browser `Origin` header with `403 Forbidden`.
`Rule 4`	Prompt-Injection Tool Escalation on `/v1`	`/v1/chat/completions` defaults to zero tools and only exposes tools explicitly passed via `--allow-tool` that also declare `annotations.readOnlyHint === true`.
`Rule 5`	Unauthenticated Dashboard Key Theft	`POST /admin/v1/open-dashboard` opens a local browser tab rather than returning any key in the HTTP response body, and is rate-limited to once every 10 seconds.
`Rule 6`	Invisible Background Execution	Tools run inside a visible browser tab with an interactive tool catalog and live invocation counter.
`Rule 7`	Forgotten Wildcard `/v1` Exposure	Wildcard `*` on `/v1` is restricted to pure chat (zero tools), expires automatically (15m TTL), and triggers a persistent security warning banner.

Normative Documentation

Overview & Architecture (docs/index.md)

Why static sites need client-side WebMCP and how the three-part architecture fits together.

繁體中文

MCP Pages Specification (docs/spec.md)

Page structure, URL normalization, navigator.modelContext shim, and tool annotations.

繁體中文

Relay Wire Protocol (docs/protocol.md)

/tab/*, /mcp, /v1, and /admin/v1/* endpoints, JSON-RPC ID rewriting, and reconnect grace window.

繁體中文

Security Model & Threat Analysis (docs/security.md)

Detailed analysis of all seven security rules for shared GitHub Pages origins.

繁體中文