How to make this whole system work · Edition 2026.05

From a fresh machine to a trace on PlatAtlas in five steps.

PlatAtlas surveys what your team builds. mcp-tape records what your agents do. Together they give you a queryable atlas of the org + a frame-by-frame replay of every MCP session that touched it.

Which machine?

This setup runs on any machine that has Node 20+. The MCP client you connect to it varies by platform — pick the row that matches your host.

Host	MCP client	Notes
Windows 10 / 11	Antigravity 2.0 IDE (x64)	Native install from antigravity.google. Also supports Claude Code, Claude Desktop, Gemini CLI side-by-side. `mcp-tape install` shipped Windows-PATHEXT + path-resolver fixes in 0.3.0 — works first try.
macOS	Antigravity 2.0 IDE · Claude Desktop · Claude Code	Antigravity macOS build supports the iframe contract (MCP Apps) sooner than Linux. If you want in-IDE atlas rendering today, this is the host.
Linux x86_64	Antigravity 2.0 · Claude Code · Gemini CLI	Same as macOS but as the VS Code-derived Linux build.
Linux aarch64 (Raspberry Pi 4/5)	Claude Code · Gemini CLI	Antigravity is x64-only desktop. Pi runs Claude Code natively — substitute it for the build session, everything else identical. Confirmed working on Pi 5 / Bookworm aarch64.

01Install mcp-tape globally

One npm install, then one auto-wire command. Requires Node 20 or newer.

npm i -g mcp-tape

Then wrap every MCP client config on disk in one shot:

mcp-tape install

install walks every detected client config (Claude Code, Claude Desktop, Google Antigravity, Gemini CLI) and inserts the mcp-tape proxy in front of every entry in mcpServers. Your original config is backed up to <file>.mcp-tape.bak. Idempotent; safe to run after upgrades.

Client	Config file
claude-code	`~/.claude.json`
claude-desktop (macOS)	`~/Library/Application Support/Claude/claude_desktop_config.json`
claude-desktop (Linux)	`~/.config/Claude/claude_desktop_config.json`
antigravity	`~/.gemini/antigravity/mcp_config.json`
gemini-cli	`~/.gemini/settings.json`

02Restart your client + use it normally

Restart Claude Code / Claude Desktop / Antigravity / your IDE. Every MCP server invocation now flows through mcp-tape. JSONL traces land in ./mcp-traces/ next to the working directory — one file per session per server, named like 2026-05-22T13-30-00-000Z-<label>.jsonl.

No traffic leaves your machine yet. mcp-tape writes to local disk only. Uploading is opt-in (step 04).

Show the org action in real time (live-mode side-screen)

Add --serve 7777 to the mcp-tape invocation in your client's config — it starts a localhost WebSocket on port 7777 that broadcasts every JSON-RPC frame as it's captured. On a second screen or window, open:

# Live frames render side-by-side with your org's atlas as the agent acts:
open "https://<your-org>.platatlas.com/?atlas=examples/<your-org>&live=ws://127.0.0.1:7777"

# Or the standalone field-book live view (no atlas context):
open "https://mcpreplay.dev/?live=ws://127.0.0.1:7777"

The big screen shows your agent (Antigravity, Claude Code, …) doing the work; the side screen shows the timeline of every tool call as it happens, with the atlas context behind it. Reconnects automatically on transient disconnects via the ?since=<lastSeq> grammar so brief drops don't lose frames.

03Open a trace in your browser

Two surfaces render the exact same JSONL — pick whichever fits the moment:

Surface	Where	Best for
mcpreplay.dev	Standalone field-book at mcpreplay.dev	Sharing a trace publicly; reading the open JSONL format spec; learning the tool. Drag-drop landing + full docs.
Mcpreplay tab (this site)	The leftmost tab on any `<org>.platatlas.com` page	Reviewing build traces inside your org's atlas context. Tight in-frame viewer — the field-book landing is intentionally stripped here, so the panel jumps straight to the timeline.

Two equivalent ways to view the same trace:

# Standalone (the full mcp-replay experience):
open https://mcpreplay.dev/?trace=<jsonl-url>

# In-atlas (renders only the timeline, side by side with the org's plat):
open "https://<org>.platatlas.com/?atlas=examples/<org>&trace=<jsonl-url>"

The Mcpreplay tab loads /replay.html?embed=1&trace=… internally. The embed=1 flag hides the field-book landing and renders only the trace viewer. No JSON-RPC frames travel up to the parent page — everything stays inside the iframe.

04Publish a trace (optional, public)

To share a recording — for a bug report, an onboarding demo, a portfolio piece — upload it with one flag:

mcp-tape upload --public ./mcp-traces/2026-05-22T13-30-00-000Z-server.jsonl
# → https://mcpreplay.dev/?trace=https://traces.mcpreplay.dev/<uuid>.jsonl

The trace lives in R2; the URL is a stable shareable link. Same URL works at <your-org>.platatlas.com/?atlas=...&trace=<url> too.

05Sign in + sync to your org's atlas

To attribute traces to your GitHub identity (so they appear on your org's atlas with author metadata + private-by-default visibility), sign in once:

open https://<your-org>.platatlas.com/auth/github/login

Then bulk-sync any local trace directory:

platatlas sync ~/mcp-traces/

Each JSONL gets a UUID and lands in D1, attributed to your GitHub login. Visible on the org's Atlas tab grouped by uploader; openable inline via the Mcpreplay tab.

What you get

A queryable architectural record of your org — every package, every flow, every named milestone.
Frame-by-frame replay of every MCP session that touched the codebase.
A shareable URL for any trace — public or org-scoped.
Compatible with any MCP client that reads a standard config file. No client lock-in.
Open trace format (spec). Anything can produce or consume it.

The build's environment is recorded too

Every per-org atlas has an environment.json next to nodes.json that records what was in the room while the build happened: toolchain versions, agents that reviewed the work, humans who decided things. View it via the Conditions tab.

mcp-tape traces will soon include the same dimension as additive JSONL frames: dir: "env" (toolchain snapshot at trace-start + mid-session changes), dir: "ext" (PR reviews / CI / deploys that shaped the next decision), dir: "actor" (who/what was at the keyboard). Schema lives at web/examples/_schema/environment.md in the workflow-atlas repo. Older mcp-replay versions render these as generic frames; an upcoming release styles them distinctly.

Need a new org instance?

Every GitHub org gets its own subdomain — <org>.platatlas.com. To spin up a new instance, see the operator runbook at proxy-worker/DEPLOY.md in the workflow-atlas repo.

PlatAtlas · Edition 2026.05 · Vol. I. Published in Sacramento, CA. Source at github.com/PlatAtlas/workflow-atlas.