diff --git a/docs/README.md b/docs/README.md
index e859e8e..4fab8ba 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -5,6 +5,7 @@ Additional documentation for mcpc.
 ## Contents
 
 - [Claude Skill](./claude-skill/) - Claude Code skill for AI agents using mcpc
+- [VHS demos](./vhs/) - VHS tape files for recording demo GIFs of mcpc
 - [CONTRIBUTING.md](../CONTRIBUTING.md) - Development, contributing, and publishing guide
 
 ## Main documentation
diff --git a/docs/vhs/README.md b/docs/vhs/README.md
new file mode 100644
index 0000000..e4e8884
--- /dev/null
+++ b/docs/vhs/README.md
@@ -0,0 +1,79 @@
+# mcpc demo recordings (VHS)
+
+This folder contains [VHS](https://github.com/charmbracelet/vhs) tape files
+that record terminal GIFs of mcpc. Each `.tape` is a small script that drives
+a real shell session; VHS replays it, captures the output, and renders a GIF
+(or MP4 / WebM) — no manual screen recording needed.
+
+## Prerequisites
+
+- **VHS** — `brew install vhs` (or see [installation guide](https://github.com/charmbracelet/vhs#installation))
+- **mcpc** — `npm install -g @apify/mcpc`
+- **jq** — needed by `scripting.tape`
+- **Auth (optional)** — `export APIFY_TOKEN=...` if you want the demos to hit
+  the authenticated Apify MCP server. Drop the `--header` line from the tape
+  to record an anonymous session against any public MCP server instead.
+
+## Tapes
+
+| File | Records | Notes |
+| ---- | ------- | ----- |
+| [`mcpc-demo.tape`](./mcpc-demo.tape) | Flagship overview: discover → connect → tools → grep → call → JSON → close | Source for `docs/images/mcpc-demo.gif` |
+| [`quickstart.tape`](./quickstart.tape) | Minimal "connect, list, call" flow | Hero-sized GIF for README top |
+| [`tools.tape`](./tools.tape) | `tools-list`, `tools-get`, `tools-call`, inline JSON, stdin | |
+| [`scripting.tape`](./scripting.tape) | `--json` piped through `jq` and `xargs` (code mode) | |
+| [`grep.tape`](./grep.tape) | Dynamic tool discovery with `mcpc grep` | |
+| [`proxy.tape`](./proxy.tape) | MCP proxy / AI sandboxing | |
+
+## Recording
+
+Each tape outputs a GIF in this directory. Run from inside `docs/vhs/`:
+
+```bash
+cd docs/vhs
+vhs mcpc-demo.tape          # → mcpc-demo.gif
+vhs quickstart.tape         # → quickstart.gif
+# ... etc
+```
+
+To refresh the demo embedded in the main README:
+
+```bash
+cd docs/vhs
+vhs mcpc-demo.tape
+cp mcpc-demo.gif ../images/mcpc-demo.gif
+```
+
+You can also render `.mp4` or `.webm` by editing the `Output` directive
+inside the tape file (VHS infers the format from the extension).
+
+## Customising
+
+`mcpc-demo.tape` is the template — copy it, trim the sections you don't need,
+and adjust:
+
+- `Output <file>` — destination GIF / MP4 / WebM
+- `Set Width / Set Height` — frame size (current default: 1100×650)
+- `Set FontSize` / `Set FontFamily` / `Set Theme` — appearance
+- `Set TypingSpeed` / `Sleep` — pacing
+- Server URL and `--header` — point at your own MCP server
+- Tool / argument names — swap for tools your audience cares about
+
+The other tapes use the same Set block so they look consistent side by side.
+
+## Tips
+
+- Use `Hide` / `Show` around setup commands (clearing the screen, closing
+  stale sessions, exporting `PS1`) so they don't appear in the GIF.
+- Add `Sleep` after each `Enter` so viewers have time to read the output
+  before the next command runs.
+- `Set PlaybackSpeed 1.5` speeds up the final GIF without changing the
+  recording cadence — handy for long demos.
+- Run the tape locally first (`vhs <file>.tape`) and inspect the generated
+  GIF before committing. VHS does not run inside CI by default; the tapes
+  are version-controlled but the GIFs they produce are not (the main
+  `docs/images/mcpc-demo.gif` is checked in separately).
+
+See the [VHS documentation](https://github.com/charmbracelet/vhs#vhs-command-reference)
+for the full list of directives (`Type`, `Sleep`, `Enter`, `Hide`, `Show`,
+`Wait`, `Screenshot`, all `Set …` options, etc.).
diff --git a/docs/vhs/grep.tape b/docs/vhs/grep.tape
new file mode 100644
index 0000000..d3cde81
--- /dev/null
+++ b/docs/vhs/grep.tape
@@ -0,0 +1,56 @@
+# mcpc grep — dynamic tool discovery across sessions
+#
+#   cd docs/vhs && vhs grep.tape
+
+Output grep.gif
+
+Require mcpc
+
+Set Shell           "bash"
+Set FontFamily      "JetBrains Mono"
+Set FontSize        16
+Set Width           1100
+Set Height          600
+Set Padding         20
+Set TypingSpeed     50ms
+Set Theme           "Catppuccin Mocha"
+Set WindowBar       Colorful
+Set WindowBarSize   32
+Set BorderRadius    8
+
+Hide
+Type "export PS1='$ '"
+Enter
+Type "mcpc connect mcp.apify.com @apify --header \"Authorization: Bearer ${APIFY_TOKEN}\" >/dev/null 2>&1 || true"
+Enter
+Type "clear"
+Enter
+Show
+
+Type "# Find tools by keyword across every live session"
+Sleep 600ms
+Enter
+Type 'mcpc grep "scraper"'
+Sleep 400ms
+Enter
+Sleep 4s
+
+Type "clear"
+Enter
+Type "# Regex + case-sensitive, limited results"
+Sleep 500ms
+Enter
+Type 'mcpc grep "search|find" -E -m 5'
+Sleep 400ms
+Enter
+Sleep 4s
+
+Type "clear"
+Enter
+Type "# Search resources and prompts too"
+Sleep 500ms
+Enter
+Type 'mcpc grep "config" --resources --prompts'
+Sleep 400ms
+Enter
+Sleep 4s
diff --git a/docs/vhs/mcpc-demo.tape b/docs/vhs/mcpc-demo.tape
new file mode 100644
index 0000000..7d1d700
--- /dev/null
+++ b/docs/vhs/mcpc-demo.tape
@@ -0,0 +1,179 @@
+# mcpc demo — flagship overview
+#
+# Generate the GIF with VHS (https://github.com/charmbracelet/vhs):
+#
+#   cd docs/vhs && vhs mcpc-demo.tape
+#
+# This produces mcpc-demo.gif in the current directory. To update the demo
+# embedded in the main README, copy it to docs/images/mcpc-demo.gif.
+#
+# Prerequisites:
+#   - VHS:  brew install vhs   (or see https://github.com/charmbracelet/vhs#installation)
+#   - mcpc: npm install -g @apify/mcpc
+#   - jq:   brew install jq    (for the scripting section)
+#   - Auth: export APIFY_TOKEN=... (or remove the --header line to use anonymous access)
+#
+# This is a template — adapt the commands below for your own server,
+# tools, and audience. Use the focused tapes in this folder
+# (quickstart.tape, tools.tape, scripting.tape, grep.tape, proxy.tape)
+# as a starting point for shorter, single-feature demos.
+
+Output mcpc-demo.gif
+
+Require mcpc
+
+# Look & feel
+Set Shell           "bash"
+Set FontFamily      "JetBrains Mono"
+Set FontSize        16
+Set Width           1100
+Set Height          650
+Set Padding         20
+Set TypingSpeed     50ms
+Set PlaybackSpeed   1.0
+Set Theme           "Catppuccin Mocha"
+Set WindowBar       Colorful
+Set WindowBarSize   32
+Set BorderRadius    8
+Set CursorBlink     true
+
+# Hidden setup: clean prompt, no scrollback, fresh state
+Hide
+Type "export PS1='$ '"
+Enter
+Type "mcpc @apify close 2>/dev/null; mcpc @fs close 2>/dev/null; true"
+Enter
+Type "clear"
+Enter
+Show
+
+# 1. Discover mcpc
+Type "# mcpc — a universal MCP CLI client"
+Sleep 800ms
+Enter
+Sleep 600ms
+
+Type "mcpc --help | head -25"
+Sleep 400ms
+Enter
+Sleep 4s
+
+Type "clear"
+Enter
+Sleep 300ms
+
+# 2. List sessions and OAuth profiles
+Type "# No sessions or profiles yet"
+Sleep 600ms
+Enter
+Sleep 400ms
+
+Type "mcpc"
+Sleep 400ms
+Enter
+Sleep 3s
+
+# 3. Connect to a remote MCP server
+Type "# Connect to Apify's MCP server as session @apify"
+Sleep 600ms
+Enter
+Sleep 400ms
+
+Type 'mcpc connect mcp.apify.com @apify --header "Authorization: Bearer ${APIFY_TOKEN}"'
+Sleep 400ms
+Enter
+Sleep 3s
+
+# 4. Server info, capabilities, instructions
+Type "# Show server capabilities and instructions"
+Sleep 600ms
+Enter
+Sleep 400ms
+
+Type "mcpc @apify"
+Sleep 400ms
+Enter
+Sleep 4s
+
+Type "clear"
+Enter
+Sleep 300ms
+
+# 5. List available tools
+Type "# List available tools"
+Sleep 600ms
+Enter
+Sleep 400ms
+
+Type "mcpc @apify tools-list | head -15"
+Sleep 400ms
+Enter
+Sleep 4s
+
+# 6. Dynamic tool discovery
+Type "clear"
+Enter
+Type "# Find tools by keyword — useful for AI agents"
+Sleep 600ms
+Enter
+Sleep 400ms
+
+Type 'mcpc @apify grep "scraper"'
+Sleep 400ms
+Enter
+Sleep 4s
+
+# 7. Inspect a tool's schema
+Type "clear"
+Enter
+Type "# Inspect a tool's input schema"
+Sleep 600ms
+Enter
+Sleep 400ms
+
+Type "mcpc @apify tools-get search-actors"
+Sleep 400ms
+Enter
+Sleep 5s
+
+# 8. Call a tool
+Type "clear"
+Enter
+Type "# Call a tool with key:=value arguments"
+Sleep 600ms
+Enter
+Sleep 400ms
+
+Type 'mcpc @apify tools-call search-actors keywords:="web scraper" limit:=3'
+Sleep 400ms
+Enter
+Sleep 5s
+
+# 9. JSON mode + jq for scripting (code mode)
+Type "clear"
+Enter
+Type "# JSON mode composes with jq for scripts and agents"
+Sleep 600ms
+Enter
+Sleep 400ms
+
+Type "mcpc --json @apify tools-list | jq -r '.[].name' | head -5"
+Sleep 400ms
+Enter
+Sleep 4s
+
+# 10. Close the session
+Type "# Close the session when done"
+Sleep 600ms
+Enter
+Sleep 400ms
+
+Type "mcpc @apify close"
+Sleep 400ms
+Enter
+Sleep 2s
+
+Type "# Learn more: https://github.com/apify/mcpc"
+Sleep 2s
+Enter
+Sleep 1500ms
diff --git a/docs/vhs/proxy.tape b/docs/vhs/proxy.tape
new file mode 100644
index 0000000..33485ef
--- /dev/null
+++ b/docs/vhs/proxy.tape
@@ -0,0 +1,69 @@
+# mcpc proxy — AI sandbox: expose a credentialed session without leaking tokens
+#
+#   cd docs/vhs && vhs proxy.tape
+
+Output proxy.gif
+
+Require mcpc
+
+Set Shell           "bash"
+Set FontFamily      "JetBrains Mono"
+Set FontSize        16
+Set Width           1200
+Set Height          700
+Set Padding         20
+Set TypingSpeed     50ms
+Set Theme           "Catppuccin Mocha"
+Set WindowBar       Colorful
+Set WindowBarSize   32
+Set BorderRadius    8
+
+Hide
+Type "export PS1='$ '"
+Enter
+Type "mcpc @relay close 2>/dev/null; mcpc @sandbox close 2>/dev/null; true"
+Enter
+Type "clear"
+Enter
+Show
+
+Type "# Human authenticates once and exposes a localhost MCP proxy"
+Sleep 600ms
+Enter
+Type 'mcpc connect mcp.apify.com @relay --header "Authorization: Bearer ${APIFY_TOKEN}" --proxy 8080'
+Sleep 400ms
+Enter
+Sleep 4s
+
+Type "# The proxy forwards MCP traffic but hides the upstream token"
+Sleep 600ms
+Enter
+Type "mcpc"
+Sleep 400ms
+Enter
+Sleep 4s
+
+Type "clear"
+Enter
+Type "# An AI agent (or another tool) connects to the proxy as a normal MCP server"
+Sleep 600ms
+Enter
+Type "mcpc connect localhost:8080 @sandbox"
+Sleep 400ms
+Enter
+Sleep 3s
+
+Type "mcpc @sandbox tools-list | head -8"
+Sleep 400ms
+Enter
+Sleep 5s
+
+Type "clear"
+Enter
+Type "# Tear down both sides"
+Sleep 500ms
+Enter
+Type "mcpc @sandbox close && mcpc @relay close"
+Sleep 400ms
+Enter
+Sleep 2s
diff --git a/docs/vhs/quickstart.tape b/docs/vhs/quickstart.tape
new file mode 100644
index 0000000..7696d81
--- /dev/null
+++ b/docs/vhs/quickstart.tape
@@ -0,0 +1,59 @@
+# mcpc quickstart — first-time user flow
+#
+# A minimal demo of "install → connect → list tools → call tool".
+# Best for the README hero / landing-page GIF.
+#
+#   cd docs/vhs && vhs quickstart.tape
+
+Output quickstart.gif
+
+Require mcpc
+
+Set Shell           "bash"
+Set FontFamily      "JetBrains Mono"
+Set FontSize        16
+Set Width           1100
+Set Height          600
+Set Padding         20
+Set TypingSpeed     50ms
+Set Theme           "Catppuccin Mocha"
+Set WindowBar       Colorful
+Set WindowBarSize   32
+Set BorderRadius    8
+
+Hide
+Type "export PS1='$ '"
+Enter
+Type "mcpc @apify close 2>/dev/null; true"
+Enter
+Type "clear"
+Enter
+Show
+
+Type "# Connect to any MCP server, get a stateful session"
+Sleep 600ms
+Enter
+Type 'mcpc connect mcp.apify.com @apify --header "Authorization: Bearer ${APIFY_TOKEN}"'
+Sleep 400ms
+Enter
+Sleep 3s
+
+Type "# List the tools the server exposes"
+Sleep 500ms
+Enter
+Type "mcpc @apify tools-list | head -10"
+Sleep 400ms
+Enter
+Sleep 4s
+
+Type "# Call one of them with typed key:=value arguments"
+Sleep 500ms
+Enter
+Type 'mcpc @apify tools-call search-actors keywords:="web scraper" limit:=3'
+Sleep 400ms
+Enter
+Sleep 5s
+
+Type "mcpc @apify close"
+Enter
+Sleep 2s
diff --git a/docs/vhs/scripting.tape b/docs/vhs/scripting.tape
new file mode 100644
index 0000000..87a16c6
--- /dev/null
+++ b/docs/vhs/scripting.tape
@@ -0,0 +1,69 @@
+# mcpc scripting — JSON mode + jq + pipelines (code mode)
+#
+#   cd docs/vhs && vhs scripting.tape
+
+Output scripting.gif
+
+Require mcpc
+Require jq
+
+Set Shell           "bash"
+Set FontFamily      "JetBrains Mono"
+Set FontSize        16
+Set Width           1200
+Set Height          700
+Set Padding         20
+Set TypingSpeed     50ms
+Set Theme           "Catppuccin Mocha"
+Set WindowBar       Colorful
+Set WindowBarSize   32
+Set BorderRadius    8
+
+Hide
+Type "export PS1='$ '"
+Enter
+Type "mcpc connect mcp.apify.com @apify --header \"Authorization: Bearer ${APIFY_TOKEN}\" >/dev/null 2>&1 || true"
+Enter
+Type "clear"
+Enter
+Show
+
+Type "# --json emits MCP-spec JSON to stdout, errors to stderr"
+Sleep 600ms
+Enter
+Type "mcpc --json @apify tools-list | jq -r '.[].name' | head -5"
+Sleep 400ms
+Enter
+Sleep 4s
+
+Type "clear"
+Enter
+Type "# Chain tools across calls with jq + xargs"
+Sleep 500ms
+Enter
+Type "mcpc --json @apify tools-call search-actors keywords:=\"scraper\" limit:=1 \\"
+Sleep 200ms
+Enter
+Type '  | jq -r ".content[0].text | fromjson | .[0].name"'
+Sleep 400ms
+Enter
+Sleep 5s
+
+Type "clear"
+Enter
+Type "# Snapshot every tool's schema for CI / contract tests"
+Sleep 500ms
+Enter
+Type "for tool in $(mcpc --json @apify tools-list | jq -r '.[].name' | head -3); do"
+Sleep 200ms
+Enter
+Type '  mcpc --json @apify tools-get "$tool" > "/tmp/$tool.json"'
+Sleep 200ms
+Enter
+Type "  echo \"saved /tmp/$tool.json\""
+Sleep 200ms
+Enter
+Type "done"
+Sleep 400ms
+Enter
+Sleep 6s
diff --git a/docs/vhs/tools.tape b/docs/vhs/tools.tape
new file mode 100644
index 0000000..532da89
--- /dev/null
+++ b/docs/vhs/tools.tape
@@ -0,0 +1,66 @@
+# mcpc tools — list / get / call
+#
+#   cd docs/vhs && vhs tools.tape
+
+Output tools.gif
+
+Require mcpc
+
+Set Shell           "bash"
+Set FontFamily      "JetBrains Mono"
+Set FontSize        16
+Set Width           1100
+Set Height          650
+Set Padding         20
+Set TypingSpeed     50ms
+Set Theme           "Catppuccin Mocha"
+Set WindowBar       Colorful
+Set WindowBarSize   32
+Set BorderRadius    8
+
+Hide
+Type "export PS1='$ '"
+Enter
+Type "mcpc connect mcp.apify.com @apify --header \"Authorization: Bearer ${APIFY_TOKEN}\" >/dev/null 2>&1 || true"
+Enter
+Type "clear"
+Enter
+Show
+
+Type "# Browse the tools exposed by the server"
+Sleep 600ms
+Enter
+Type "mcpc @apify tools-list | head -15"
+Sleep 400ms
+Enter
+Sleep 4s
+
+Type "clear"
+Enter
+Type "# Inspect a single tool's input schema and description"
+Sleep 500ms
+Enter
+Type "mcpc @apify tools-get search-actors"
+Sleep 400ms
+Enter
+Sleep 5s
+
+Type "clear"
+Enter
+Type "# Call with auto-parsed key:=value arguments"
+Sleep 500ms
+Enter
+Type 'mcpc @apify tools-call search-actors keywords:="web scraper" limit:=3'
+Sleep 400ms
+Enter
+Sleep 5s
+
+Type "clear"
+Enter
+Type "# Pass complex JSON inline or from stdin"
+Sleep 500ms
+Enter
+Type 'echo '"'"'{"keywords":"crawler","limit":2}'"'"' | mcpc @apify tools-call search-actors'
+Sleep 400ms
+Enter
+Sleep 5s