From 2ea2a735cd73e585e8f2a5492348b062418a1cf5 Mon Sep 17 00:00:00 2001 From: Blake Bauman Date: Tue, 25 Aug 2026 17:12:18 -0700 Subject: [PATCH] feat(site,docs): the demo is answering again, so point at it again MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The demo gateways were redeployed today — fold-demo-tasks, fold-demo and fold-enterprise are back on tasks/demo/enterprise.fold.run, all three healthy, with the walkthrough verified end to end against the running gateway (three namespaces federate, a minted task polls from a session that never saw it minted). This restores what #44 removed once the thing it pointed at was gone: the homepage demo section and its styles, the nav and footer demo links, the docs walkthrough and its sidebar entry, and the benchmarks bullet warning against benchmarking the demo. The status page stays gone, and the uptime worker stays undeployed. It watched the fold cloud as well as the demo, and the fold cloud is still down — every one of api, broker, mcp and console answers 522 — so a status page would come up mostly red and argue against the demo the rest of this commit is restoring. The two sentences that sent readers to /status for live state are dropped rather than left dangling; the page comes back when there is a cloud for it to report on. Co-Authored-By: Claude Opus 5 (1M context) --- apps/docs/astro.config.mjs | 1 + apps/docs/src/content/docs/benchmarks.md | 1 + apps/docs/src/content/docs/try-the-demo.md | 119 ++++++++++++++++ apps/site/src/layouts/Base.astro | 3 + apps/site/src/pages/index.astro | 158 +++++++++++++++++++++ 5 files changed, 282 insertions(+) create mode 100644 apps/docs/src/content/docs/try-the-demo.md diff --git a/apps/docs/astro.config.mjs b/apps/docs/astro.config.mjs index 60da27a..c622fbd 100644 --- a/apps/docs/astro.config.mjs +++ b/apps/docs/astro.config.mjs @@ -58,6 +58,7 @@ export default defineConfig({ sidebar: [ { label: 'Getting started', slug: 'getting-started' }, { label: 'Run it locally', slug: 'run-it-locally' }, + { label: 'Try the live demo', slug: 'try-the-demo' }, { label: 'The console', slug: 'console' }, { label: 'Use cases', slug: 'use-cases' }, { label: 'Configuration', slug: 'configuration' }, diff --git a/apps/docs/src/content/docs/benchmarks.md b/apps/docs/src/content/docs/benchmarks.md index aacf53b..ee4b0a8 100644 --- a/apps/docs/src/content/docs/benchmarks.md +++ b/apps/docs/src/content/docs/benchmarks.md @@ -77,6 +77,7 @@ Read that table with care, in two places. The direct column serves *one* upstrea - **Retention is the honest throughput framing.** The direct column is an in-process SDK server doing near-zero work per call; fold adds a full second hop through the same SDK. Against a real upstream doing real work, the relative overhead shrinks toward the latency gate's ~0.2 ms. - **Sessions are the unit of concurrency.** Each load-test connection is a full SDK client session, with fold holding a per-client upstream session behind it — the deployment-realistic shape, not an artificial socket storm. One untuned instance, default config. - **The gate and the typical number are different things.** 5 ms is a regression tripwire that has to survive noisy shared runners; ~0.2 ms is what the same instrument reports on quiet hardware. Quote the second, rely on the first. +- **Don't benchmark the [demo](/try-the-demo/).** demo.fold.run is rate-limited, containerized on fractional-vCPU hardware, and fronted by Cloudflare — it demonstrates federation, not fold's ceiling. The harness is one command; run that instead. In production, the same questions are answered continuously by the [`fold_request_duration_seconds` and `fold_upstream_request_duration_seconds` histograms](/operations/#metrics) — the difference between them is the gateway's share of every real request. diff --git a/apps/docs/src/content/docs/try-the-demo.md b/apps/docs/src/content/docs/try-the-demo.md new file mode 100644 index 0000000..4614431 --- /dev/null +++ b/apps/docs/src/content/docs/try-the-demo.md @@ -0,0 +1,119 @@ +--- +title: Try the live demo +description: Walk through demo.fold.run — three public MCP servers behind one governed endpoint, including federated tasks and the live console. +--- + + + +`https://demo.fold.run/mcp` is a real fold gateway — the unmodified release binary — federating three public MCP servers. No signup, no key: point any MCP client (or `curl`) at it. Rate-limited, unauthenticated, no warranty. + +| Namespace | Upstream | Notes | +|---|---|---| +| `cfdocs__*` | Cloudflare's MCP docs server | A real third-party upstream | +| `git__*` | GitMCP | A public 2025-era server on the session handshake — behind the gateway, just another namespace | +| `jobs__*` | fold-demo-tasks | A task-minting server (Go, on the official SDK); where the [federated-tasks story](https://fold.run/blog/federating-mcp-tasks/) runs live | + +Every example below is plain `curl`. Responses arrive as a one-event SSE body — read the `data:` line. + +## 0. Open a session + +fold's client side is the official Go SDK's streamable HTTP server, so requests ride a session: `initialize` once, capture the `Mcp-Session-Id` response header, send it on everything after. + +```bash +DEMO=https://demo.fold.run/mcp +SID=$(curl -s -D - -o /dev/null -X POST $DEMO \ + -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \ + -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2026-07-28","capabilities":{},"clientInfo":{"name":"me","version":"0"}}}' \ + | grep -i mcp-session-id | tr -d '\r' | cut -d' ' -f2) + +curl -s -o /dev/null -X POST $DEMO -H "mcp-session-id: $SID" \ + -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \ + -d '{"jsonrpc":"2.0","method":"notifications/initialized"}' +``` + +The `initialize` result already shows the gateway working: `serverInfo.name` is `fold`, and the instructions line names the three namespaces. + +## 1. One virtual server + +```bash +curl -s -X POST $DEMO -H "mcp-session-id: $SID" \ + -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \ + -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' +``` + +One merged tool list — `cfdocs__*`, `git__*`, and `jobs__*` side by side. fold fanned the request out to all three upstreams, namespaced the names, and merged the results in one page (deterministic order, cursor-paginated past `routing.pageSize`). If an upstream were down you'd still get the other two, with the failure named in `_meta["run.fold/partialFailure"]` instead of a dead endpoint. Repeat calls inside the TTL are served from the [list cache](/configuration/). + +## 2. Start a long-running job + +```bash +curl -s -X POST $DEMO -H "mcp-session-id: $SID" \ + -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \ + -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"jobs__start_job","arguments":{"label":"my job","seconds":15}}}' +``` + +The minted task rides the result's `_meta`, origin-tagged by the gateway: + +```json +{ "result": { + "_meta": { + "task": { "taskId": "demo-job-2", "status": "working", "label": "my job", "remainingMs": 14999, "createdAt": "…" }, + "pollIntervalMs": 1000, + "run.fold/upstream": "demo-tasks" + }, + "content": [{ "type": "text", "text": "started demo-job-2 (\"my job\", 15s) — poll it with tasks/get" }] } } +``` + +Because the mint is visible in `_meta`, fold pinned `taskId → upstream` affinity as the response passed through — and a tool call is a tool call, so deny-by-default policy would have applied at mint and the call is in the audit trail. + +## 3. Poll it — fold routes to the owner + +```bash +curl -s -X POST $DEMO -H "mcp-session-id: $SID" \ + -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \ + -d '{"jsonrpc":"2.0","id":4,"method":"tasks/get","params":{"taskId":"demo-job-2"}}' +``` + +`tasks/list` shows the merged view across the whole federation — your job in task-id order, with `_meta["run.fold/partialFailure"]` naming the two upstreams that don't speak tasks at all: + +```bash +curl -s -X POST $DEMO -H "mcp-session-id: $SID" \ + -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \ + -d '{"jsonrpc":"2.0","id":5,"method":"tasks/list"}' +``` + +No tool name, no routing hint — fold resolves the owner from its affinity index, or by a read-only probe across upstreams for a task it never saw minted (try it: task ids survive sessions, so `tasks/get` from a brand-new session still finds the owner). Mutating methods are never fanned out; `tasks/cancel` and `tasks/result` locate first, then act on the owner alone. The mechanism is the subject of [the launch post](https://fold.run/blog/federating-mcp-tasks/). + +## 4. The 2025-era upstream you address the same way + +```bash +curl -s -X POST $DEMO -H "mcp-session-id: $SID" \ + -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \ + -d '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"git__fetch_generic_documentation","arguments":{"owner":"modelcontextprotocol","repo":"servers"}}}' +``` + +GitMCP speaks the 2025-era session handshake. fold — built on the official Go SDK on both sides of the proxy — holds its own client session to it, so from where you're standing it's just another namespace in the same tool list, behind the same governance. + +## 5. Watch it in the console + +Open **[demo.fold.run/console](https://demo.fold.run/console/)** — the read-only [fold console](/console/), enabled in the demo's config. The dashboard shows the three upstreams, their breaker state, and the deployment facts live, and **[the map view](https://demo.fold.run/console/#/upstreams?view=map)** draws the federation itself: one gateway node fanning out to cfdocs, git, and jobs, each route carrying that upstream's current breaker state. It's generated from `/api/federation`, so it's this demo's real topology, not a picture of one. The test console is a plain MCP client against the same `/mcp` endpoint you've been curling, governed and audited like any other caller. + +## Run this yourself + +The demo is assembled from one config — the same shape as any fold deployment ([configuration reference](/configuration/)): + +```jsonc +{ + "upstreams": [ + { "id": "cf-docs", "url": "https://docs.mcp.cloudflare.com/mcp", "namespace": "cfdocs" }, + { "id": "gitmcp", "url": "https://gitmcp.io/docs", "namespace": "git" }, + { "id": "demo-tasks", "url": "https://tasks.fold.run/mcp", "namespace": "jobs" } + ], + "server": { + "rateLimit": { "requestsPerMinute": 300 }, + "introspection": { "enabled": true }, + "console": { "enabled": true } + } +} +``` + +`go run github.com/fold-run/fold/cmd/fold@latest --config fold.config.json` gives you the same thing in front of your own servers — see [Getting started](/getting-started/). diff --git a/apps/site/src/layouts/Base.astro b/apps/site/src/layouts/Base.astro index 95bea63..ac40da2 100644 --- a/apps/site/src/layouts/Base.astro +++ b/apps/site/src/layouts/Base.astro @@ -847,6 +847,7 @@ const { BenchmarksHonest numbers, caveats attached + Live demo Blog GitHub Get started @@ -864,6 +865,8 @@ const {