1. Home
  2. mcp-proxy
  3. mcp-proxy for Claude Code: Setup & Config

Data as of

mcp-proxy for Claude Code: Setup & Config

Claude Code: mcp-proxy bridges MCP transport mismatches between clients and servers.

What you can do with mcp-proxy in Claude Code

Pick it to bridge existing MCP transports and route named local servers without replacing their tools.

  • Connect a stdio-only client to a remote MCP endpoint.
  • Pass authentication headers or OAuth2 credentials to an upstream service.

Before you start: mcp-proxy in Claude Code

  • mcp-proxy installed using uv or pipx
  • uvx and the mcp-server-fetch package for this documented example
  • An MCP-compatible client

This README example exposes a local fetch stdio server through the proxy. Install mcp-proxy with uv tool install mcp-proxy or pipx install mcp-proxy first. The opposite mode takes an upstream URL; choose --transport=streamablehttp for a Streamable HTTP upstream.

mcp-proxy Claude Code configuration

  1. Choose Claude Code configuration scope

    For mcp-proxy, open Project scope: .mcp.json at the repository root. Project JSON: merge into mcpServers; user scope: use the CLI.

  2. Add mcp-proxy to Claude Code

    Use the mcp-proxy entry below in mcpServers. Keep mcp-proxy's documented sse connection fields and your other Claude Code entries.

  3. Check mcp-proxy in Claude Code

    mcp-proxy: Inspect claude mcp list and /mcp status.

Config file · Project scope: .mcp.json at the repository root

JSON
{
  "mcpServers": {
    "mcp-proxy": {
      "type": "sse",
      "url": "http://127.0.0.1:8080/sse"
    }
  }
}

CLI (POSIX shell)
claude mcp add-json --scope project 'mcp-proxy' '{"type":"sse","url":"http://127.0.0.1:8080/sse"}'

Troubleshooting mcp-proxy in Claude Code

  • Inspect claude mcp list, then mcp-proxy's connection to 127.0.0.1:8080 in /mcp. Complete Claude Code authentication only for a trusted service.
  • mcp-proxy: check sse connectivity to 127.0.0.1:8080 from Claude Code; a stdio command is not a replacement for this endpoint.
  • Transport mismatch: mcp-proxy's catalog lists stdio; the displayed Claude Code configuration uses sse.
  • Known limitation: Wrapped server executables and dependencies must be available separately.
  • Known limitation: The default container image does not include uv.
  • Known limitation: Named-server timeout and transportType fields are ignored.
  • General Claude Code troubleshooting lives in the /clients/claude-code guide.

mcp-proxy — details. Claude Code guide

Frequently asked questions

Register mcp-proxy with the displayed claude mcp add-json --scope project command, or merge the JSON into .mcp.json at the repository root.

Claude Code's mcp-proxy example uses sse. The mcp-proxy catalog lists stdio; these instructions follow the stored configuration instead.

Claude Code connects mcp-proxy to 127.0.0.1:8080 using url.

The supplied README describes transport bridging. Actual application tools come from the connected MCP servers.

No. The README explicitly says uv is not included by default and shows how to extend the image.