docs(mcp): describe the built-in proxy, not npx mcp-remote - #448
Merged
Conversation
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.
Deploying allagents with
|
| Latest commit: |
8e8abf6
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://8021b325.allagents.pages.dev |
| Branch Preview URL: | https://docs-mcp-proxy-stale-npx-ref.allagents.pages.dev |
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
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-remotepackage. This is stale — since #367,allagents mcp proxy <url>has been a from-scratch, built-in bridge with no external runtime dependency. Discovered this while answering a question about connecting to a real OAuth-protected MCP server, prompted by these exact docs.What changed
docs/.../guides/mcp-proxy.mdx— replaced everymcp-remotereference with the actual built-in proxy: nonpx/Node.js requirement, OAuth client registration + tokens cached per-server under~/.allagents/oauth-proxy/<hash>/(not~/.mcp-auth/), removed the now-fictional "Metadata File" section (~/.allagents/mcp-remote/mcp-metadata-settings.jsondoesn't exist in the current implementation), added a new "OAuth & Token Cache" section describing what actually happens.docs/.../reference/configuration.mdx— one sentence fix, same issue.examples/workspaces/mcp-proxy/README.mdand its.allagents/workspace.yamlcomments — updated the documented.codex/config.tomloutput to match reality.Verification
Ran
allagents updateagainst the example workspace and confirmed the generated.codex/config.tomlmatches what the docs now show:bun test(1362 pass),bun run typecheck,bun run lintall clean. Docs/example-only change — nosrc/code touched.