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 use 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 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 use `npx mcp-remote`.
  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 `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/
• 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

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 use mcp-remote 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": "npx",
    "args": [
      "mcp-remote",
      "https://knowledge.mcp.example.com",
      "--http",
      "--static-oauth-client-metadata",
      "@~/.allagents/mcp-remote/mcp-metadata-settings.json"
    ]
  }
}

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.

Metadata File

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:

{
  "client_uri": "http://localhost"
}

The file is created once and never overwritten, so you can customize it if needed.

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).

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.

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.