Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions apps/docs/astro.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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' },
Expand Down
1 change: 1 addition & 0 deletions apps/docs/src/content/docs/benchmarks.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
119 changes: 119 additions & 0 deletions apps/docs/src/content/docs/try-the-demo.md
Original file line number Diff line number Diff line change
@@ -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.
---

<!-- Source: the demo's own config (fold.run repo, apps/demo) — every request below was verified against the running gateway; keep in sync with the deployed federation -->

`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/).
3 changes: 3 additions & 0 deletions apps/site/src/layouts/Base.astro
Original file line number Diff line number Diff line change
Expand Up @@ -847,6 +847,7 @@ const {
<a href="https://docs.fold.run/benchmarks/"><b>Benchmarks</b><span>Honest numbers, caveats attached</span></a>
</div>
</div>
<a href="/#demo">Live demo</a>
<a href="/blog/" aria-current={current === 'blog' ? 'page' : undefined}>Blog</a>
<a href="https://github.com/fold-run/fold">GitHub</a>
<a class="btn btn-primary" href="https://docs.fold.run/getting-started/">Get started</a>
Expand All @@ -864,6 +865,8 @@ const {
</div>
<nav aria-label="Product" class="foot-col">
<h2>Product</h2>
<a href="/#demo">Live demo</a>
<a href="https://demo.fold.run/console/">Live console</a>
<a href="https://docs.fold.run/use-cases/">Use cases</a>
<a href="https://docs.fold.run/benchmarks/">Benchmarks</a>
<a href="https://docs.fold.run/conformance/">Conformance</a>
Expand Down
158 changes: 158 additions & 0 deletions apps/site/src/pages/index.astro
Original file line number Diff line number Diff line change
Expand Up @@ -181,6 +181,67 @@ const jsonld = {
</div>
</section>

<section
class="demo"
id="demo"
data-section="demo"
data-intent="prove it live"
data-layout="contained"
data-items="3"
>
<div class="wrap">
<div class="section-head">
<h2>See it live.</h2>
<p class="intro">
demo.fold.run federates three public MCP servers behind one endpoint: the unmodified
release binary, governed by its own config. Rate-limited, unauthenticated, no warranty.
Copy-paste walkthrough: <a href="https://docs.fold.run/try-the-demo/">try the demo</a>.
</p>
</div>
<!-- Two live surfaces, and the order matters: the console is the one a
reader can open in this tab, right now, without wiring up a client.
It was documented and running on the demo for weeks while the
marketing site never once mentioned it. -->
<div class="route-rail">
<a class="chip chip-link" href="https://demo.fold.run/console/">demo.fold.run/console</a>
<span class="chip">demo.fold.run/mcp</span>
<span class="muted" style="font-size: var(--body-sm)">three upstreams · one endpoint</span
>
</div>
<p class="console-note">
The console ships inside the binary and needs no client. Open it and you are reading the
running federation: live latency and breaker state per upstream, the policy in effect, the
rate limit. Its test console calls the same endpoint everything else does. The topology
at the top of this page is drawn by hand; <a
href="https://demo.fold.run/console/#/upstreams?view=map">the console draws its own</a
> from the federation it is serving.
</p>
<div class="termini">
<article class="terminus">
<h3>cfdocs__*</h3>
<p>
Cloudflare's public docs MCP server — a real third-party upstream, governed and
namespaced like any internal one.
</p>
</article>
<article class="terminus">
<h3>git__*</h3>
<p>
GitMCP — a public 2025-era server on the session handshake. Behind the gateway it is
just another namespace.
</p>
</article>
<article class="terminus">
<h3>jobs__*</h3>
<p>
A task-minting demo server. Start a job, then poll it with nothing but the task id —
fold routes every poll to the owner.
</p>
</article>
</div>
</div>
</section>

<section
class="runit"
id="run"
Expand Down Expand Up @@ -983,6 +1044,100 @@ const jsonld = {
gap: var(--spacing-md);
}
}
.termini {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
gap: var(--spacing-md);
}
.terminus {
background: var(--color-rack);
border: 1px solid var(--color-trace);
border-radius: var(--radius);
background: var(--color-rack);
border: 1px solid var(--color-trace);
border-radius: var(--radius-lg);
padding: var(--spacing-lg);
position: relative;
}
.terminus::before {
/* fold-line connector notch: each terminus hangs off the shared route */
content: '';
position: absolute;
top: -13px;
left: var(--spacing-lg);
width: 1px;
height: 12px;
border-left: 1px solid var(--color-trace);
}
.route-rail {
margin-bottom: var(--spacing-md);
display: flex;
align-items: flex-end;
gap: var(--spacing-sm);
flex-wrap: wrap;
}
/* the count sits at the far end, the chips group at the near one */
.route-rail .muted {
margin-left: auto;
}
/* The console chip is the only clickable thing in the rail, so it carries
Signal text and a live dot against the mcp chip's Carrier. */
.route-rail .chip-link {
color: var(--color-fg);
display: inline-flex;
align-items: center;
gap: 8px;
transition:
border-color 0.18s cubic-bezier(0.25, 1, 0.5, 1),
background-color 0.18s cubic-bezier(0.25, 1, 0.5, 1);
}
.route-rail .chip-link::before {
content: '';
width: 6px;
height: 6px;
border-radius: 50%;
background: var(--color-accent);
flex: none;
}
.route-rail .chip-link:hover {
background: var(--color-rack-hi);
border-color: var(--color-trace-hi);
text-decoration: none;
}
.console-note {
color: var(--color-static);
font-size: var(--body-sm);
line-height: var(--line-height-meta);
max-width: 78ch;
margin-bottom: var(--spacing-lg);
}
.route-rail .chip {
font-family: var(--mono-font-family);
font-size: var(--body-sm);
letter-spacing: 0;
color: var(--color-carrier);
background: var(--color-rack);
border: 1px solid var(--color-trace);
border-radius: var(--radius-sm);
padding: 3px 10px;
}
/* The namespace prefixes are literal wire strings, so they keep the mono —
the one place a heading earns it. */
.terminus h3 {
font-family: var(--mono-font-family);
font-size: 1.0625rem;
font-weight: var(--weight-heading);
letter-spacing: 0;
line-height: var(--line-height-card);
margin-bottom: var(--spacing-sm);
color: var(--color-fg);
}
.terminus p {
color: var(--color-static);
font-size: var(--body);
line-height: 1.6;
}

/* ===== run-it: numbered route ===== */
.route-steps {
display: grid;
Expand Down Expand Up @@ -1153,6 +1308,9 @@ const jsonld = {
.hero-grid {
display: none;
}
.terminus::before {
display: none;
}
.diagram-panel {
max-width: 560px;
}
Expand Down
Loading