docs(mcp): describe the built-in proxy, not npx mcp-remote (#448)

christso · web-flow · commit 0c3fbf923973 · 2026-08-04T10:27:23.000+10:00
* docs(mcp): describe the built-in proxy, not npx mcp-remote The MCP proxy guide, its example workspace, and a configuration reference all still described the pre-#367 design that shelled out to the third-party `npx mcp-remote` package, with OAuth state cached under ~/.mcp-auth/ and a ~/.allagents/mcp-remote/mcp-metadata-settings.json metadata file. None of that matches the current implementation: `allagents mcp proxy <url>` is a from-scratch, built-in bridge (no npx, no Node.js requirement beyond allagents itself), and its OAuth client registration/tokens are cached per-server under ~/.allagents/oauth-proxy/<hash>/ (see src/core/mcp-http-stdio-proxy.ts). Verified the example workspace's documented transform output against the actual generated `.codex/config.toml` by running `allagents update` against it. * docs(mcp): warn that MCP proxy needs a real install, not just npx The proxy feature writes a bare `command: "allagents"` into generated client configs (.mcp.json, .codex/config.toml, etc.), which the MCP client spawns directly later -- not through npx. Someone who only ever runs `npx allagents` for ad hoc commands would hit a "command not found" failure the first time a proxied server actually starts, without any indication why. Cross-referenced from the general installation guide's npx section too. Verified: a bare `allagents` on PATH only resolves when actually installed (npm/bun global install symlinks it), confirmed on this machine's real global install at /usr/lib/node_modules/allagents.
diff --git a/docs/src/content/docs/docs/getting-started/installation.mdx b/docs/src/content/docs/docs/getting-started/installation.mdx
@@ -19,6 +19,10 @@ Run AllAgents without installing:
 npx allagents
 ```
 
+:::note
+If you plan to use the [MCP Proxy](/docs/guides/mcp-proxy/) feature, install AllAgents globally (npm or bun) instead. The proxy command is invoked directly by your MCP clients later, not by you through npx, so `allagents` needs to already be resolvable on `PATH` at that point.
+:::
+
 ## Using bun
 
 ```bash
diff --git a/docs/src/content/docs/docs/guides/mcp-proxy.mdx b/docs/src/content/docs/docs/guides/mcp-proxy.mdx
@@ -1,11 +1,9 @@
 ---
 title: MCP Proxy
-description: Transparently proxy HTTP MCP servers through mcp-remote for clients that need stdio transport.
+description: Transparently proxy HTTP MCP servers through a built-in stdio bridge, with OAuth handled for you.
 ---
 
-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.
-
-When AllAgents generates a proxied client config, it does so through the public `allagents mcp proxy <serverUrl>` helper command.
+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 run through AllAgents' own built-in stdio bridge (`allagents mcp proxy <serverUrl>`), so all clients connect through an already-authenticated proxy — no separate package to install.
 
 ## Quick Start
 
@@ -39,7 +37,8 @@ clients:
 
 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`.
+  # Codex only speaks stdio, so rewrite its config to run through the
+  # built-in `allagents mcp proxy` bridge.
   clients:
     - codex
 ```
@@ -49,19 +48,20 @@ what each client received:
 
 ```bash
 cat .mcp.json            # Claude — original HTTP config
-cat .codex/config.toml   # Codex — rewritten to `npx mcp-remote` stdio
+cat .codex/config.toml   # Codex — rewritten to `allagents mcp proxy` 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
+with nothing more than `allagents` itself installed. 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/`
+- **OAuth handled once** — the built-in proxy runs the full PKCE authorization flow the first time it connects, then caches the client registration and tokens under `~/.allagents/oauth-proxy/`; subsequent connections reuse them (with automatic token refresh) instead of reopening a browser
 - **Stdio everywhere** — clients that only support stdio can connect to HTTP servers
 - **Transparent** — configure which clients need proxying and AllAgents rewrites configs automatically during sync
+- **Nothing extra to install** — the proxy is built into the `allagents` binary; there's no separate package to fetch or cache on first use
 
 ## Configuration
 
@@ -92,7 +92,7 @@ mcpProxy:
 2. For each server + client pair, it checks if proxying is needed:
    - Is the client listed in `mcpProxy.clients`?
    - Is there a per-server override in `mcpProxy.servers.<name>.proxy` that includes this client?
-3. If yes **and** the server uses HTTP transport (has a `url` field), the config is rewritten to use `mcp-remote` via stdio
+3. If yes **and** the server uses HTTP transport (has a `url` field), the config is rewritten to invoke `allagents mcp proxy` via stdio
 4. Stdio servers are never transformed — they pass through unchanged
 
 ### Transform Example
@@ -112,14 +112,8 @@ With `mcpProxy.clients: [claude]`, the synced config for Claude becomes:
 ```json
 {
   "knowledge-base": {
-    "command": "npx",
-    "args": [
-      "mcp-remote",
-      "https://knowledge.mcp.example.com",
-      "--http",
-      "--static-oauth-client-metadata",
-      "@~/.allagents/mcp-remote/mcp-metadata-settings.json"
-    ]
+    "command": "allagents",
+    "args": ["mcp", "proxy", "https://knowledge.mcp.example.com"]
   }
 }
 ```
@@ -147,24 +141,28 @@ In this example:
 
 Per-server `proxy` lists are additive — they extend the default `clients`, not replace them.
 
-## Metadata File
+## OAuth & Token Cache
 
-AllAgents automatically creates a metadata file at `~/.allagents/mcp-remote/mcp-metadata-settings.json` on first sync. This file is passed to `mcp-remote` via the `--static-oauth-client-metadata` flag and contains:
+The first time `allagents mcp proxy <url>` connects to a server that requires OAuth, it runs the standard authorization-code + PKCE flow: it registers a client with the server's authorization server (or reuses a cached registration), opens your browser to complete the login, and exchanges the resulting code for tokens.
 
-```json
-{
-  "client_uri": "http://localhost"
-}
+Client registration, tokens, and discovery metadata are cached per server under:
+
+```
+~/.allagents/oauth-proxy/<hash-of-server-url>/
+  client-info.json
+  tokens.json
+  code-verifier.txt
+  discovery.json
 ```
 
-The file is created once and never overwritten, so you can customize it if needed.
+Later connections reuse this cache — no browser prompt — and an expired access token is refreshed automatically using the cached refresh token, still without reopening a browser. If you ever need to force a fresh login for a specific server (e.g. a revoked token), delete that server's subdirectory and reconnect.
 
 ## Prerequisites
 
-The proxy uses `npx mcp-remote` to launch the bridge process. Because it runs through `npx`, there is nothing to install — `npx` downloads `mcp-remote` automatically on first use and caches it for subsequent runs. The only requirement is Node.js (which provides `npx`).
+None beyond `allagents` itself — the proxy has no separate runtime dependency to fetch or cache.
 
-:::note
-The first time a proxied server starts, `npx` fetches `mcp-remote` from npm, which may add a few seconds of delay. Subsequent launches use the cached package and start immediately.
+:::caution
+`allagents` must be installed and on `PATH` (`npm install -g allagents` or `bun install -g allagents`) — running it via `npx allagents` is **not** enough for this feature. The proxy command is invoked directly by each MCP client (Claude Code, Codex, etc.), not by you, and the generated config embeds a bare `command: "allagents"`. `npx` resolves and runs the package for *your own* shell invocation, but doesn't add anything to `PATH` for another process to find afterward — so a client spawning that config later will fail with "command not found" unless `allagents` is genuinely installed.
 :::
 
 ## Scope
diff --git a/docs/src/content/docs/docs/reference/configuration.mdx b/docs/src/content/docs/docs/reference/configuration.mdx
@@ -207,7 +207,7 @@ Servers AllAgents adds are tracked in `.allagents/sync-state.json`; pre-existing
 
 ## MCP Proxy
 
-The optional `mcpProxy` section rewrites HTTP MCP servers to stdio via [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) for clients that need it. See the [MCP Proxy guide](/docs/guides/mcp-proxy/) for details.
+The optional `mcpProxy` section rewrites HTTP MCP servers to stdio via AllAgents' built-in `allagents mcp proxy` bridge for clients that need it. See the [MCP Proxy guide](/docs/guides/mcp-proxy/) for details.
 
 ```yaml
 mcpProxy:
diff --git a/examples/workspaces/mcp-proxy/.allagents/workspace.yaml b/examples/workspaces/mcp-proxy/.allagents/workspace.yaml
@@ -1,4 +1,5 @@
-# Example: MCP Proxy — bridge HTTP MCP servers to stdio via mcp-remote
+# Example: MCP Proxy — bridge HTTP MCP servers to stdio via the built-in
+# `allagents mcp proxy` helper
 #
 # This workspace installs the `deepwiki` plugin from the official AllAgents
 # marketplace. The plugin provides a single HTTP MCP server (DeepWiki), which
@@ -7,9 +8,9 @@
 #   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.
+# to rewrite the HTTP config to run through the built-in `allagents mcp proxy`
+# bridge 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 \
@@ -22,10 +23,10 @@
 #
 # After sync, inspect the result:
 #   cat .mcp.json                # Claude — original HTTP config
-#   cat .codex/config.toml       # Codex — rewritten to `npx mcp-remote` stdio
+#   cat .codex/config.toml       # Codex — rewritten to `allagents mcp proxy` stdio
 #
 # Requirements:
-#   - Node.js (for `npx mcp-remote`)
+#   - None beyond `allagents` itself
 
 repositories: []
 
@@ -41,7 +42,7 @@ clients:
 
 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.
+  # run through `allagents mcp proxy` for these clients. Claude is omitted
+  # because it supports HTTP MCP natively.
   clients:
     - codex
diff --git a/examples/workspaces/mcp-proxy/README.md b/examples/workspaces/mcp-proxy/README.md
@@ -4,16 +4,15 @@ 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.
+server (`https://mcp.deepwiki.com/mcp`), and proxies it through AllAgents'
+own built-in stdio bridge 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` |
+| `codex`  | stdio via `allagents mcp proxy` | `.codex/config.toml` |
 
 ## Running it
 
@@ -43,8 +42,9 @@ 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
+[mcp_servers.deepwiki]
+command = "allagents"
+args = ["mcp", "proxy", "https://mcp.deepwiki.com/mcp"]
 ```
 
 DeepWiki is a public, no-auth server, so you can connect immediately and
@@ -53,11 +53,9 @@ 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.
+None beyond `allagents` itself — the proxy is built into the binary, with
+no separate package to fetch or cache on first use.
 
 ## See also
 
 - [MCP Proxy guide](https://allagents.dev/docs/guides/mcp-proxy/)
-- [`mcp-remote` on npm](https://www.npmjs.com/package/mcp-remote)
