MCP Proxy

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

The fastest way to try MCP proxy is to scaffold the ready-made examples/workspaces/mcp-proxy workspace with allagents workspace init --from:

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:

.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 run through the
  # built-in `allagents mcp proxy` bridge.
  clients:
    - codex

workspace init also runs the initial sync, so you can immediately inspect what each client received:

cat .mcp.json            # Claude — original HTTP config
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 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 — 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

Add an mcpProxy section to your workspace.yaml:

mcpProxy:
  clients:
    - claude
    - copilot
  servers:
    my-internal-api:
      proxy:
        - codex

Fields

Field	Required	Description
clients	Yes	Default list of clients where all HTTP servers are proxied
servers	No	Per-server overrides
servers.<name>.proxy	Yes (if server entry exists)	Additional clients to proxy this specific server for

How It Works

1. During allagents update, AllAgents collects MCP servers from installed plugins
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 invoke allagents mcp proxy via stdio
4. Stdio servers are never transformed — they pass through unchanged

Transform Example

A plugin provides an HTTP MCP server:

{
  "knowledge-base": {
    "url": "https://knowledge.mcp.example.com"
  }
}

With mcpProxy.clients: [claude], the synced config for Claude becomes:

{
  "knowledge-base": {
    "command": "allagents",
    "args": ["mcp", "proxy", "https://knowledge.mcp.example.com"]
  }
}

Other clients not listed in mcpProxy.clients receive the original HTTP config unchanged.

Per-Server Overrides

The servers map lets you proxy specific servers for additional clients beyond the default list:

mcpProxy:
  clients:
    - claude
  servers:
    my-internal-api:
      proxy:
        - codex
        - copilot

In this example:

• All HTTP servers are proxied for claude (from the default clients list)
• Only my-internal-api is additionally proxied for codex and copilot

Per-server proxy lists are additive — they extend the default clients, not replace them.

OAuth & Token Cache

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.

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

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

None beyond allagents itself — the proxy has no separate runtime dependency to fetch or cache.

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

MCP proxy works with both project-scoped and user-scoped syncs.

Project Scope

During allagents update, proxied servers are written to each client’s project-level MCP config file:

Client	Config File
Claude	.mcp.json
VS Code	.vscode/mcp.json
Copilot	.copilot/mcp-config.json
Codex	.codex/config.toml

User Scope

When using --scope user, proxied servers are synced via client CLI commands (claude mcp add, codex mcp add) to user-level config, making them available across all projects.