@winstonsayno/mcp-gateway 1.0.1 → 1.2.0

package/CHANGELOG.md

@@ -9,6 +9,102 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-10-07
+
+Security hardening and more of the MCP spec on `/mcp`. Every new protection that could reject traffic that 1.1
+accepted is **opt-in**; see *Upgrade notes*.
+
+### Security
+- **Hashed API keys**: `auth.apiKeys` entries (plain strings or `key`) may be `sha256:<64 hex>` digests, so the config
+  file never holds a usable key. Digest and plain form of a key share the same client id. New CLI commands
+  `mcp-gateway gen-key` (random `mgw_…` key + digest, `--bytes`, `--prefix`, `--json`) and
+  `mcp-gateway hash-key [key]` (reads stdin when no argument is given). Malformed `sha256:` values are a config error.
+- **Key expiry / disabling**: `expiresAt` (ISO 8601) and `disabled` on object keys → `401`; open `/mcp` sessions of
+  such keys end on the next reload. Keys expiring within 7 days produce a warning.
+- **JWT hardening** (`auth.jwt`): `issuer`, `audience` (string or list), `algorithms` allowlist, `clockToleranceSeconds`,
+  `requireExp`, `maxTokenAgeSeconds`; verification keys from `jwtSecret` (HS*), a PEM `publicKey` (RS/PS/ES/EdDSA) or
+  a `jwksUrl` (HTTPS, cached `jwksCacheSeconds`, refetch on unknown `kid`). HMAC and asymmetric algorithms are never
+  mixed (algorithm-confusion protection); exactly one key source must be configured.
+- **Security headers** (`security.headers`, default on): `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`,
+  `Referrer-Policy: no-referrer`, `Cross-Origin-Opener-Policy`, `Cross-Origin-Resource-Policy`, a deny-all CSP on API
+  responses and a dashboard CSP that allows exactly its inline script by SHA-256 hash. Optional `security.hsts`.
+- **Network guards**: `security.ipAllowlist` (IPv4 / IPv6 / CIDR, via `net.BlockList`), `security.allowedHosts` (Host
+  header allowlist with `*.domain` wildcards), `security.trustProxy` (Express "trust proxy": decides `req.ip` for rate
+  limits, lockout, allowlist and logs). Liveness / readiness probes stay reachable.
+- **DNS-rebinding protection** (`security.dnsRebindingProtection`): Host must be a loopback name / the bind address
+  (or `allowedHosts`), and `/mcp` accepts browser `Origin`s only when same-origin, loopback or explicitly listed.
+- **Size limits**: `security.maxBodyBytes` (default 10 MiB as before, now configurable for REST and `/mcp`) and
+  `security.maxToolArgumentsBytes` for `tools/call`, `prompts/get` and `completion/complete` arguments (`413` on REST,
+  `-32602` on `/mcp`).
+- **Brute-force lockout** (`security.authLockout`): after `maxFailures` (10) failed authentications from one IP within
+  `windowSeconds` (300), the IP gets `429` + `Retry-After` for `lockoutSeconds` (900) on every authenticated route,
+  including `/mcp` and `/api/v1/events`.
+- **Secret redaction**: log lines and metadata, recorded `errorMessage`s (request log, audit log, `/requests`,
+  `/stats`, `/events`, dashboard) mask Bearer / Basic tokens, JWTs, common provider keys (OpenAI, Anthropic, GitHub,
+  GitLab, Slack, AWS, Google), `password=` / `token=` / `api_key=` pairs, URL credentials and values under
+  secret-looking keys. `GET /servers` now also masks secret-looking stdio `args` (`--token x`, `--api-key=x`). Extra
+  patterns via `security.redactPatterns`.
+- **Secure-defaults check**: startup warnings / hints (auth off on a public bind, DNS rebinding, `/mcp` open to any
+  origin, plain-text / short / expiring keys, JWT without iss / aud / exp, no lockout, `corsOrigins: ["*"]` with auth,
+  headers disabled, error details exposed). `mcp-gateway validate` prints them; `--strict` exits with code 2.
+- `GET /api/v1/security`: auth strategy, warnings, key hygiene counts and upcoming expiries, JWT settings, effective
+  security settings and lockout state — never key material; scoped clients get `403`. The dashboard's *Connect*
+  page shows it as a *Security posture* card (demo mock updated).
+- `SECURITY.md`: hardening table and scope; `docs/deployment.md` security checklist extended.
+
+### Fixed (security)
+- Unexpected errors (500) no longer return their message and stack trace whenever `NODE_ENV` was not `production`
+  (the default for `npm i -g` installs). They are shown only with `NODE_ENV=development` or the new
+  `security.exposeErrorDetails: true`. Deliberate `GatewayError` details are unchanged.
+
+### Added (MCP)
+- **Progress notifications**: a single `tools/call` with `params._meta.progressToken` from a client that accepts
+  `text/event-stream` is forwarded with a gateway-generated token; upstream `notifications/progress` are mapped back
+  and the reply becomes an SSE stream (progress events, then the result). Plain JSON otherwise.
+- **Logging**: `logging` capability, `logging/setLevel` per session; upstream `notifications/message` are forwarded to
+  sessions in scope at or above their level (`logger: "<serverId>/<logger>"`), and upstream servers announcing
+  `logging` are set to the most verbose level any session requested (re-applied after reconnects).
+- **Completion**: `completions` capability and `completion/complete` routed by prompt (exposed name translated back)
+  or resource template / URI; servers without the capability answer an empty completion.
+- **Resource subscriptions**: `resources.subscribe` capability, `resources/subscribe` / `resources/unsubscribe`
+  (routed like `resources/read`; `-32601` when the owning server does not support subscriptions) and
+  `notifications/resources/updated` forwarding. One upstream subscription per (server, URI) is shared and
+  reference-counted across sessions, released when the last session unsubscribes or ends, and restored after an
+  upstream reconnect.
+- Proxy: `RequestOptions.onProgress`, `connected` and `notification` events.
+- Library exports: `hashApiKey`, `isHashedKey`, `buildJwtVerifier`, `HMAC_ALGORITHMS`, `ASYMMETRIC_ALGORITHMS`,
+  `redactString`, `redactValue`, `redactArgs`, `configureRedaction`, `securityWarnings`, `AuthLockout`,
+  `createIpMatcher`, `hostAllowed`, `dashboardCsp`, `inlineScriptHashes`, `LOG_LEVELS`; types `SecurityConfig`,
+  `JwtConfig`, `AuthLockoutConfig`, `SecurityWarning`, `McpLogLevel`, `RequestOptions`, `ProgressUpdate`.
+
+### Changed
+- `auth.jwtSecret` is no longer required for `strategy: jwt` when `auth.jwt.publicKey` or `auth.jwt.jwksUrl` is set.
+- `initialize` on `/mcp` now also announces `logging`, `completions` and `resources.subscribe` (clients ignore
+  capabilities they do not use).
+- JWT verification failures are logged with the client IP.
+
+### Upgrade notes
+- No configuration changes are required. New behaviour that is on by default: security headers (disable with
+  `security.headers: false`), secret redaction in logs / recorded error messages, hidden 500 error details, and the
+  extra capabilities on `/mcp`.
+- If you embedded the dashboard in an `<iframe>` on another origin, set `security.headers: false` (the new
+  `frame-ancestors 'none'` / `X-Frame-Options: DENY` block that).
+- Tests or tooling that relied on 500 responses carrying `error.message` / `details` outside production need
+  `NODE_ENV=development` or `security.exposeErrorDetails: true`.
+- Everything else (`ipAllowlist`, `allowedHosts`, `dnsRebindingProtection`, `authLockout`, `maxToolArgumentsBytes`,
+  `hsts`, `trustProxy`, JWT checks, key expiry) is opt-in.
+
+## [1.1.0] - 2026-10-07
+
+### Added
+- **Dashboard v2** (`/dashboard`, still one self-contained HTML file: no build step, no CDN, no runtime dependencies):
+  - First-run **guided onboarding** (dismissible, reopen with **?**): connect with an API key (tested live), see the upstream servers, try a tool (`tools` list → form generated from the tool's JSON schema, or raw JSON → call → result), and copy-paste snippets for Claude Desktop (via `mcp-remote`), Cursor, Claude Code, the JS and Kotlin clients and curl, all pointing at this gateway's `/mcp` URL.
+  - **Live overview**: requests/min, p50 / p95 / p99 latency, error rate and servers-online cards with sparklines; hand-drawn SVG charts for request rate, latency and error rate (5 m / 15 m / 1 h / 6 h windows, hover / touch tooltips); top tools; usage per API key; live request stream; server health.
+  - Servers page with tool chips and one-click reconnect; Playground; request history with filters and cursor paging (cards on phones); Connect page.
+  - English / 中文 toggle, dark / light theme, responsive down to phone widths with a bottom tab bar, keyboard navigation (arrow-key tabs, focus-trapped dialog, Esc), `prefers-reduced-motion`, View Transitions, skeleton loaders; animations use transform / opacity only.
+- `GET /api/v1/stats`: windowed time series (count, errors, p50 / p95 per bucket), summary, top tools, per-server and per-client usage (`?window=`, `?bucket=`).
+- `GET /api/v1/events`: Server-Sent Events stream with a `request` event per recorded call and a `snapshot` (server health + summary) every 2 s; heartbeats, max 50 concurrent streams, closed on shutdown. Both new endpoints require auth and show restricted clients only their own calls. The dashboard falls back to polling every 2 s when the stream is unavailable.
+
 ## [1.0.1] - 2026-10-07
 
 Bug-fix release; no API or configuration changes.

package/README.md

@@ -21,6 +21,8 @@ Route · Authenticate · Rate-limit · Monitor — all your [Model Context Proto
 
 ---
 
+> **Live demo:** try the dashboard with simulated traffic — <https://harrisoncn.github.io/mcp-gateway/> (runs entirely in your browser).
+
 ## The Problem
 
 As [MCP](https://modelcontextprotocol.io) becomes the standard protocol for AI agents to interact with tools, teams are running **dozens of MCP servers** — filesystem, GitHub, databases, Slack, search, and more. Managing them is chaos:
@@ -63,10 +65,11 @@ As [MCP](https://modelcontextprotocol.io) becomes the standard protocol for AI a
 ## Features
 
 - **Unified API endpoint** — one URL for all your MCP tools, auto-routed by tool name
-- **MCP endpoint for clients** — `/mcp` speaks MCP Streamable HTTP (2025-06-18 / 2025-03-26), so Claude Code, Cursor or any MCP client sees every upstream tool through one server, with the same auth, limits and metrics
+- **MCP endpoint for clients** — `/mcp` speaks MCP Streamable HTTP (2025-06-18 / 2025-03-26), so Claude Code, Cursor or any MCP client sees every upstream tool through one server, with the same auth, limits and metrics — including progress notifications, cancellation, logging, completions and resource subscriptions
 - **Every MCP transport** — `stdio`, `streamable-http` (current spec), legacy `sse` (HTTP+SSE) and `websocket` upstream servers, with per-server headers for upstream auth
 - **Automatic reconnect** — crashed or disconnected servers are reconnected with exponential backoff + jitter; state is visible in `/servers`, `/health`, the dashboard and Prometheus
-- **Authentication** — API key (constant-time compare), JWT (HS256/384/512), or no-auth; misconfiguration fails closed
+- **Authentication** — API keys (constant-time compare, storable as `sha256:` digests, with expiry), JWT (HMAC secret, PEM public key or JWKS URL; issuer / audience / exp checks), or no-auth; misconfiguration fails closed
+- **Hardening** — security headers + hash-based CSP, IP allowlist, Host / Origin checks against DNS rebinding, body and argument size limits, brute-force lockout, secret redaction in logs and history, startup security warnings (`mcp-gateway validate --strict`)
 - **Rate limiting** — per-key sliding-window counter, with standard `X-RateLimit-*` headers
 - **Per-key scopes** — restrict an API key (or a JWT via claims) to some servers / tools and give it its own rate limit; enforced on REST and `/mcp`
 - **Concurrency limits** — per-server `maxConcurrency`, queued requests count against `timeout`
@@ -199,9 +202,9 @@ What the endpoint does:
 
 | | |
 |---|---|
-| `POST /mcp` | JSON-RPC: `initialize`, `ping`, `tools/list` (paginated), `tools/call`, `resources/list`, `resources/templates/list`, `resources/read`, `prompts/list`, `prompts/get`, notifications (incl. `notifications/cancelled`). Batches are accepted. Responses are `application/json`. |
-| `GET /mcp` | SSE stream for server→client notifications: `notifications/tools/list_changed`, `notifications/resources/list_changed` and `notifications/prompts/list_changed` are sent when the aggregated list a session sees changes (a server announces changes, connects, is removed by hot reload, …). |
-| Resources & prompts | Resource URIs are passed through unchanged; when two servers list the same URI the lowest server id wins. `resources/read` is routed by exact URI, then by resource template, then to the only server with resources. Prompt names follow `toolNaming` like tools. `resources/subscribe` is not offered. |
+| `POST /mcp` | JSON-RPC: `initialize`, `ping`, `tools/list` (paginated), `tools/call`, `resources/list`, `resources/templates/list`, `resources/read`, `resources/subscribe` / `unsubscribe`, `prompts/list`, `prompts/get`, `logging/setLevel`, `completion/complete`, notifications (incl. `notifications/cancelled`). Batches are accepted. Responses are `application/json`; a single `tools/call` with `_meta.progressToken` switches to an SSE reply when the upstream reports progress (`notifications/progress`, then the result). |
+| `GET /mcp` | SSE stream for server→client notifications: `notifications/tools/list_changed`, `notifications/resources/list_changed` and `notifications/prompts/list_changed` are sent when the aggregated list a session sees changes (a server announces changes, connects, is removed by hot reload, …); `notifications/resources/updated` for subscribed URIs; upstream `notifications/message` at or above the session's `logging/setLevel` level (`logger` = `<serverId>/<logger>`). |
+| Resources & prompts | Resource URIs are passed through unchanged; when two servers list the same URI the lowest server id wins. `resources/read` is routed by exact URI, then by resource template, then to the only server with resources. Prompt names follow `toolNaming` like tools. `resources/subscribe` is routed the same way; sessions share one upstream subscription per URI, restored after reconnects. `completion/complete` is routed by prompt name or resource template. |
 | `DELETE /mcp` | Ends the session. |
 | Sessions | `initialize` returns `Mcp-Session-Id`; later requests must send it (`400` if missing, `404` if unknown or expired). A session is bound to the API key / JWT subject that created it. Idle sessions expire after `mcp.sessionIdleTimeoutSeconds`. |
 | Tool names | `toolNaming: auto` (default) keeps a tool's name unless two servers expose the same name; then every copy becomes `<serverId>__<tool>`. `prefix` always uses `<serverId>__<tool>`. Ordering is deterministic (server id, then tool name). In `auto` mode the prefixed form is also accepted by `tools/call`. |
@@ -228,6 +231,8 @@ What the endpoint does:
 | `GET` | `/api/v1/prompts` | Prompts of all servers (`?server=`) |
 | `POST` | `/api/v1/prompts/get` | Get a prompt: `{"name": "...", "server"?: "...", "arguments"?: {...}}` |
 | `GET` | `/api/v1/requests` | Request history, newest first (`?limit=` max 500, `server`, `tool`, `client`, `success`, `via`, `kind`, `since`, `until`, `cursor`) |
+| `GET` | `/api/v1/stats` | Live dashboard data: time series (count, errors, p50/p95 per bucket), summary, top tools, per-server and per-key usage (`?window=`, `?bucket=` ms) |
+| `GET` | `/api/v1/events` | Server-Sent Events: a `request` event per call, a `snapshot` (health + summary) every 2 s |
 | `POST` `GET` `DELETE` | `/mcp` | MCP Streamable HTTP endpoint (see [above](#use-the-gateway-as-an-mcp-server-mcp)) |
 
 `/health` and `/metrics` are unauthenticated by default; set `auth.protect.health` / `auth.protect.metrics`
@@ -290,11 +295,13 @@ auth:
   strategy: api-key           # none | api-key | jwt   (oauth2 is not implemented and is rejected)
   apiKeys:
     - "your-secret-key"       # full access
+    - "sha256:…"              # a key stored as its digest (mcp-gateway gen-key / hash-key)
     - key: "${APP_KEY}"       # scoped key (see "Per-key scopes")
       name: app
       servers: ["github"]
       tools: ["read_*"]
       rateLimit: { limit: 30, windowSeconds: 60 }
+      expiresAt: "2027-01-01" # optional expiry; disabled: true switches a key off
   protect:
     health: false             # true → /api/v1/health requires auth
     metrics: false            # true → /api/v1/metrics requires auth (configure your scraper)
@@ -321,6 +328,12 @@ monitor:
   prometheus: true            # Enable Prometheus /metrics
   retentionHours: 24          # Metrics retention
 
+security:                     # hardening (see docs/configuration.md#security)
+  authLockout: true           # 429 for IPs with repeated auth failures
+  dnsRebindingProtection: false  # true for a local gateway without auth
+  ipAllowlist: ["10.0.0.0/8"]
+  maxToolArgumentsBytes: 262144
+
 corsOrigins:
   - "https://your-app.com"
 
@@ -538,10 +551,18 @@ readinessProbe:
 
 ## Dashboard
 
-Open `http://localhost:4000/dashboard`. When auth is enabled, paste an API key (or JWT) in the header:
-it is kept in the browser tab (`sessionStorage`, or `localStorage` with “remember”) and sent as
-`Authorization: Bearer …` on every API call. The page itself contains no data; set `dashboard.enabled: false`
-to stop serving it.
+Open `http://localhost:4000/dashboard`. The first visit opens a short guided setup: connect with an API key,
+see the upstream servers, call a tool from a form generated from its JSON schema, and copy a ready-made
+config for Claude Desktop, Cursor, Claude Code, the JS / Kotlin clients or curl. Reopen it any time with the
+**?** button. After that the dashboard shows live request rate, p50 / p95 latency, error rate, top tools,
+usage per key, a live request stream, server health (with reconnect) and the filterable request history.
+It is one static file with no build step and no CDN; English / 中文, dark / light, and it works on phones.
+
+![Dashboard overview](docs/images/dashboard-overview.png)
+
+When auth is enabled the key is kept in the browser tab (`sessionStorage`, or `localStorage` with
+“remember”) and sent as `Authorization: Bearer …` on every API call. The page itself contains no data; set
+`dashboard.enabled: false` to stop serving it. See [dashboard/README.md](dashboard/README.md).
 
 ## Embed as a Library
 
@@ -558,6 +579,18 @@ await gateway.start();
 process.on('SIGTERM', () => gateway.stop());
 ```
 
+## What's New in v1.2
+
+| Feature | Description |
+|---------|-------------|
+| **Hashed & expiring keys** | `auth.apiKeys` entries can be `sha256:<hex>` digests (`mcp-gateway gen-key`, `hash-key`) and carry `expiresAt` / `disabled` |
+| **JWT hardening** | `auth.jwt`: `issuer`, `audience`, `algorithms` (HMAC / asymmetric never mixed), `clockToleranceSeconds`, `requireExp`, `maxTokenAgeSeconds`, PEM `publicKey` or cached `jwksUrl` (works with OAuth 2.0 / OIDC providers) |
+| **`security` block** | headers + dashboard CSP, `hsts`, `trustProxy`, `ipAllowlist`, `allowedHosts`, `dnsRebindingProtection`, `maxBodyBytes`, `maxToolArgumentsBytes`, `authLockout`, `redactPatterns` — all hot reloadable |
+| **Secure-defaults check** | startup warnings, `validate --strict`, `GET /api/v1/security` and a *Security posture* card in the dashboard |
+| **More of MCP on `/mcp`** | `notifications/progress` (SSE replies), `logging/setLevel` + forwarded `notifications/message`, `completion/complete`, `resources/subscribe` / `unsubscribe` + `notifications/resources/updated` |
+
+Details and upgrade notes: [CHANGELOG](CHANGELOG.md#120---2026-10-07).
+
 ## What's New in v1.0
 
 | Feature | Description |
@@ -607,8 +640,11 @@ unknown fields). Deep imports, log format, the dashboard and the audit database
 | JS / Kotlin clients, OpenAI / Anthropic tool schemas | ✅ Done (v1.0) |
 | Resources & prompts passthrough, persistent audit log | ✅ Done (v1.0) |
 | Stable API, docs, container image | ✅ Done (v1.0) |
+| Security hardening (hashed keys, JWKS, lockout, DNS-rebinding guard, CSP) | ✅ Done (v1.2) |
+| Progress, logging, completions, resource subscriptions on `/mcp` | ✅ Done (v1.2) |
 | Redis-backed rate limiting | 📋 Planned |
-| OAuth2 / OIDC auth | 📋 Planned |
+| OAuth2 / OIDC auth | 🟡 JWT access tokens via `auth.jwt.jwksUrl` (v1.2); discovery / token introspection planned |
+| Forwarding sampling / elicitation / roots requests to downstream clients | 📋 Planned |
 | Tool-level access control | ✅ Done via per-key scopes (v0.6) |
 | Request replay & debugging | 📋 Planned (history is available via the audit log) |
 | Multi-tenant mode | 📋 Planned |

package/dashboard/README.md

@@ -1,27 +1,76 @@
 # mcp-gateway Dashboard
 
-A lightweight, zero-dependency web dashboard for monitoring your mcp-gateway instance in real time.
+A guided, real-time web dashboard for mcp-gateway. It is **one self-contained file** (`index.html`):
+no build step, no CDN, no runtime dependencies. Charts are hand-drawn SVG.
 
-## Features
-
-- Live server status (online / degraded / reconnecting / offline) with next retry and reconnect count
-- Tool inventory across all registered servers
-- Request log with method, tool name, duration, and HTTP status
-- Aggregate metrics: total requests, error rate, average / p95 latency, uptime
-- Works with auth enabled: paste an API key or JWT in the header (kept in `sessionStorage`, or `localStorage` with “remember”), sent as `Authorization: Bearer …`
-- Auto-refreshes every 10 seconds; manual refresh button available
+![Overview](../docs/images/dashboard-overview.png)
 
 ## Access
 
-When the gateway is running, the dashboard is served at:
-
 ```
 http://localhost:4000/dashboard
 ```
 
-It reads data exclusively from the gateway's own REST API (`/api/v1/*`), so no additional backend is needed.
-The page itself is a static shell without data; disable it with `dashboard: { enabled: false }`.
+The page itself contains no data. It reads everything from the gateway's own API (`/api/v1/*`), so no extra
+backend is needed. Disable it with `dashboard: { enabled: false }`. Add `?guide` to the URL to force the
+onboarding guide open.
+
+## Guided onboarding
+
+Shown on the first visit (and whenever a key is required but missing). Dismiss it with **Skip**, **Esc** or ✕;
+reopen it any time from the **?** button.
+
+1. **Connect**: paste an API key or JWT and test it (leave empty when auth is off).
+2. **Upstream servers**: what is behind the gateway, with status, transport and tool count.
+3. **Try a tool**: pick any tool your key may use; a form is generated from its JSON schema (strings, numbers,
+   integers, booleans, enums, arrays / objects as JSON, required fields, defaults, descriptions), or switch to
+   raw JSON. Call it and see the result.
+4. **Connect your client**: copy-paste config for Claude Desktop (through `mcp-remote`), Cursor, Claude Code,
+   the TypeScript client (`clients/js`), the Kotlin client (`clients/kotlin`) and curl, all pointing at this
+   gateway's `/mcp` URL. Snippets use `<YOUR_API_KEY>` unless you choose to insert your key.
+
+## Pages
+
+| Page | What it shows |
+|---|---|
+| **Overview** | Requests/min, p50 / p95 / p99 latency, error rate and servers online (with sparklines); request-rate, latency and error-rate charts (5 m – 6 h windows, hover / touch tooltips); top tools; usage per API key; live request stream (pausable); server health |
+| **Servers** | One card per upstream server: status, transport, last ping, tools (click to try one), last error and next retry, **Reconnect** |
+| **Playground** | The same schema-driven tool runner as the guide, with search and *copy as curl* |
+| **History** | `GET /api/v1/requests` with server / tool / client / result / via / kind filters and cursor paging (audit log when enabled) |
+| **Connect** | The client snippets from the guide |
+
+## Live data
+
+- `GET /api/v1/events` (Server-Sent Events) pushes every request as it happens plus a health / summary
+  snapshot every 2 s. The dashboard reads it with `fetch()` so the API key travels in the `Authorization`
+  header (`EventSource` cannot send headers). If the stream is unavailable it polls every 2 s and keeps
+  retrying the stream with backoff. The header pill shows **Live**, **Polling** or **Offline**.
+- `GET /api/v1/stats?window=…` provides the time series and breakdowns.
+
+See [docs/api-reference.md](../docs/api-reference.md#live-data-dashboard).
+
+## Auth
+
+When auth is enabled, the key is kept in the browser tab (`sessionStorage`) or, with “Remember on this device”,
+in `localStorage`, and sent as `Authorization: Bearer …`. Scoped keys only see their own calls and in-scope
+servers and tools.
+
+## Accessibility & UX
+
+- English / 中文 toggle (defaults to the browser language), dark / light theme (defaults to the OS setting).
+- Responsive down to phone widths, with a bottom tab bar on small screens; safe-area aware.
+- Keyboard: arrow keys move between tabs, the guide is a focus-trapped modal, **Esc** closes dialogs,
+  visible focus rings, a skip link.
+- Respects `prefers-reduced-motion`. Animations only use `transform` / `opacity`; page and theme switches use
+  View Transitions where the browser supports them; skeleton loaders while data loads.
+
+## Screenshots
+
+| | |
+|---|---|
+| ![Onboarding](../docs/images/dashboard-onboarding-try-tool.png) | ![Playground (中文)](../docs/images/dashboard-playground-zh.png) |
+| ![Light theme](../docs/images/dashboard-overview-light.png) | ![Mobile](../docs/images/dashboard-mobile-zh.png) |
 
-## Screenshot
+## Demo build
 
-The dashboard uses a GitHub-dark colour scheme and is fully responsive down to mobile widths.
+`demo/mock.js` replaces `fetch` for the gateway API with an in-browser simulation (servers, tools, request stream, SSE events). The GitHub Pages workflow (`.github/workflows/pages.yml`) injects it before the dashboard script and publishes the result to <https://harrisoncn.github.io/mcp-gateway/>. It is not shipped in the npm package or Docker image.