docs(mcp-proxy): add copy-and-run example workspace

docs/src/content/docs/docs/guides/mcp-proxy.mdx

@@ -5,6 +5,56 @@ description: Transparently proxy HTTP MCP servers through mcp-remote for clients
 
 Some MCP servers use HTTP transport with OAuth authentication, but not every AI client supports HTTP natively. The MCP proxy feature rewrites HTTP server configs to use [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) as a local stdio bridge, so all clients connect through an already-authenticated proxy.
 
+## Quick Start
+
+The fastest way to try MCP proxy is to scaffold the ready-made
+[`examples/workspaces/mcp-proxy`](https://github.com/EntityProcess/allagents/tree/main/examples/workspaces/mcp-proxy)
+workspace with `allagents workspace init --from`:
+
+```bash
+allagents workspace init ./mcp-proxy-demo \
+  --from EntityProcess/allagents/examples/workspaces/mcp-proxy
+cd ./mcp-proxy-demo
+```
+
+This creates a workspace pre-configured with the `deepwiki` plugin — a real
+public HTTP MCP server (`https://mcp.deepwiki.com/mcp`) — and an `mcpProxy`
+section that rewrites it to stdio for Codex while leaving Claude's HTTP
+config untouched:
+
+```yaml
+# .allagents/workspace.yaml
+repositories: []
+
+plugins:
+  # Real HTTP MCP server from the official AllAgents marketplace.
+  # Ships a `.mcp.json` that points at https://mcp.deepwiki.com/mcp
+  - EntityProcess/allagents/plugins/deepwiki
+
+clients:
+  - claude
+  - codex
+
+mcpProxy:
+  # Claude Code supports HTTP MCP natively, so it gets the original URL.
+  # Codex only speaks stdio, so rewrite its config to use `npx mcp-remote`.
+  clients:
+    - codex
+```
+
+`workspace init` also runs the initial sync, so you can immediately inspect
+what each client received:
+
+```bash
+cat .mcp.json            # Claude — original HTTP config
+cat .codex/config.toml   # Codex — rewritten to `npx mcp-remote` stdio
+```
+
+DeepWiki is a public, no-auth MCP server, so this example works end-to-end
+with nothing more than Node.js installed (for `npx`). Point any of your
+configured clients at the workspace and you can immediately call tools like
+`read_wiki_structure` or `ask_question` against any indexed GitHub repo.
+
 ## Why Use MCP Proxy
 
 - **OAuth handled once** — `mcp-remote` manages OAuth flows and caches tokens in `~/.mcp-auth/`

examples/workspaces/mcp-proxy/.allagents/workspace.yaml

@@ -0,0 +1,47 @@
+# Example: MCP Proxy — bridge HTTP MCP servers to stdio via mcp-remote
+#
+# This workspace installs the `deepwiki` plugin from the official AllAgents
+# marketplace. The plugin provides a single HTTP MCP server (DeepWiki), which
+# is a public, no-auth server you can try without any setup:
+#
+#   https://mcp.deepwiki.com/mcp
+#
+# Some clients (e.g. Codex) only support stdio transport, so we use `mcpProxy`
+# to rewrite the HTTP config to use `npx mcp-remote` for those clients.
+# Clients that support HTTP natively (e.g. Claude Code) receive the original
+# HTTP config unchanged.
+#
+# Usage (scaffold a fresh copy anywhere):
+#   allagents workspace init ./mcp-proxy-demo \
+#     --from EntityProcess/allagents/examples/workspaces/mcp-proxy
+#   cd ./mcp-proxy-demo
+#
+# Or run in-place inside this repo:
+#   cd examples/workspaces/mcp-proxy
+#   allagents update
+#
+# After sync, inspect the result:
+#   cat .mcp.json                # Claude — original HTTP config
+#   cat .codex/config.toml       # Codex — rewritten to `npx mcp-remote` stdio
+#
+# Requirements:
+#   - Node.js (for `npx mcp-remote`)
+
+repositories: []
+
+plugins:
+  # Real HTTP MCP server from the official AllAgents marketplace.
+  # The deepwiki plugin ships a `.mcp.json` that declares:
+  #   { "deepwiki": { "type": "http", "url": "https://mcp.deepwiki.com/mcp" } }
+  - EntityProcess/allagents/plugins/deepwiki
+
+clients:
+  - claude
+  - codex
+
+mcpProxy:
+  # Every HTTP MCP server (currently just `deepwiki`) will be rewritten to
+  # use `npx mcp-remote` for these clients. Claude is omitted because it
+  # supports HTTP MCP natively.
+  clients:
+    - codex

examples/workspaces/mcp-proxy/README.md

@@ -0,0 +1,63 @@
+# MCP Proxy Example
+
+A minimal, **copy-and-run** workspace that demonstrates the
+[MCP Proxy](https://allagents.dev/docs/guides/mcp-proxy/) feature.
+
+It installs a single plugin (`deepwiki`) that exposes a real public HTTP MCP
+server (`https://mcp.deepwiki.com/mcp`), and proxies it through
+[`mcp-remote`](https://www.npmjs.com/package/mcp-remote) for Codex — which
+only supports stdio transport.
+
+## What gets synced
+
+| Client | Transport | Config file |
+|--------|-----------|-------------|
+| `claude` | HTTP (untouched) | `.mcp.json` |
+| `codex`  | stdio via `npx mcp-remote` | `.codex/config.toml` |
+
+## Running it
+
+Scaffold a fresh copy anywhere with `workspace init --from` (recommended —
+this also runs the initial sync):
+
+```bash
+allagents workspace init ./mcp-proxy-demo \
+  --from EntityProcess/allagents/examples/workspaces/mcp-proxy
+cd ./mcp-proxy-demo
+```
+
+Or, if you have this repo checked out, run it in-place:
+
+```bash
+cd examples/workspaces/mcp-proxy
+allagents update
+```
+
+Then inspect the generated files:
+
+```bash
+cat .mcp.json                 # HTTP config for Claude Code
+cat .codex/config.toml        # Rewritten stdio config for Codex
+```
+
+You should see Codex invoking:
+
+```
+npx mcp-remote https://mcp.deepwiki.com/mcp --http \
+  --static-oauth-client-metadata @~/.allagents/mcp-remote/mcp-metadata-settings.json
+```
+
+DeepWiki is a public, no-auth server, so you can connect immediately and
+ask questions like "What is the architecture of facebook/react?" from any
+proxied client.
+
+## Requirements
+
+- [Node.js](https://nodejs.org/) (provides `npx`, needed to run `mcp-remote`
+  on demand). Nothing to install globally — `npx` fetches and caches
+  `mcp-remote` automatically the first time a proxied server starts.
+
+## See also
+
+- [MCP Proxy guide](https://allagents.dev/docs/guides/mcp-proxy/)
+- [`mcp-remote` on npm](https://www.npmjs.com/package/mcp-remote)