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 {