MCPProxyGet MCPProxy ↗
← All guides and comparisons

How-to

One MCP setup for
Claude Code, Codex, OpenCode and Cursor.

Each coding agent has its own MCP config file and format. Add a server to one and the others do not know about it. With MCPProxy you add each server once and connect every client to the same local endpoint.

Last checked 2026-10-22 against MCPProxy v0.71.1 and the sources linked below.

The problem

Claude Code stores MCP servers in ~/.claude.json or a project .mcp.json. Codex uses TOML in ~/.codex/config.toml. OpenCode uses opencode.json. Cursor uses ~/.cursor/mcp.json. Same servers, four formats, four places to fix when a token changes or a package moves.

The fix: one proxy, four short entries

Claude Code ─┐
Codex       ─┤                 ┌─ GitHub
OpenCode    ─┼─►  MCPProxy  ─►─┼─ filesystem
Cursor      ─┘  (one endpoint) └─ Notion, and so on

Your servers live in MCPProxy. Each client only holds one entry that points at MCPProxy, plus its own credential.

Set it up

  1. Install and start MCPProxy.

    brew install smart-mcp-proxy/mcpproxy/mcpproxy
mcpproxy serve

    On Windows or Linux, use the installers on the download page.

  2. Bring in the servers you already have. MCPProxy can import from Claude Desktop, Claude Code, Cursor, Codex and Gemini config files. With the default settings, imported servers are held in quarantine until you approve them.

    mcpproxy upstream import ~/.claude.json
mcpproxy upstream import ~/.codex/config.toml

    Add --dry-run first to preview, and --server NAME to import one server. If a file already has an mcpproxy entry, do not import that one. You can also use the Web UI: Add Server, then Import.

  3. Approve the tools you want. Open the Web UI at the address mcpproxy serve prints (by default http://localhost:8080/ui/) and approve the servers and tools you intend to use.

  4. Connect each client. The connect wizard in the Web UI previews exactly what it will change and makes a backup first. From the command line:

    mcpproxy connect --list          # see which clients are detected
mcpproxy connect claude-code
mcpproxy connect codex
mcpproxy connect opencode
mcpproxy connect cursor

    For OpenCode, an opencode.json or opencode.jsonc must already exist. MCPProxy will not create one from scratch. Restart or reload each client afterwards.

  5. Check it worked. Ask any client to use one of your tools, then open the Activity page in the Web UI. A successful upstream tool call should be listed there with the client that made it.

Step-by-step pages with real screenshots: Claude Code, Codex, OpenCode, Cursor.

For a smaller walkthrough with real Claude Code and Codex checks, see two clients, one MCPProxy setup.

What you get from doing it this way

  • Change a server once. Update a token or swap a package in MCPProxy, and every client sees it.
  • A credential per client. mcpproxy connect writes a dedicated mcp_cli_ credential for each client instead of your admin key. You can rotate or remove one client without touching the others.
  • Different access per client. Bind a client to a profile so Cursor sees only the servers it needs. With MCPProxy started using mcpproxy serve --require-mcp-auth (or "require_mcp_auth": true), mcpproxy connect cursor --profile work-readonly binds it to a profile you created earlier. Without required authentication, MCPProxy refuses a named binding that a client could escape by leaving its credential out.
  • One log. Every call, from every client, in one activity log.
  • Review in one place. A new server or a changed tool is held once, not once per client. See detect tool poisoning and rug pulls.

Things to know

  • Agents may reach for gh or curl instead of the proxied tools. The agent instructions page has a snippet for CLAUDE.md or AGENTS.md that tells them where their tools are.
  • Per-client credentials need MCPProxy v0.70.0 or later.
  • A desktop app launched from the Dock may not inherit your shell environment, which matters if you pass the credential through an environment variable. The client pages above cover each case.
  • Claude Code and Cursor have added their own ways of loading tools on demand, so saving context is no longer the main reason to use a proxy. The main reasons are one setup, one approval step and scoped access.