Skip to content
Back to search

mcp-proxy

A bridge between Streamable HTTP and stdio MCP transports

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/sparfenyuk/mcp-proxy with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/sparfenyuk/mcp-proxy'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sparfenyuk--mcp-proxy/badge.svg)](/listings/sparfenyuk--mcp-proxy)

HTML

<a href="/listings/sparfenyuk--mcp-proxy"><img src="/api/listings/sparfenyuk--mcp-proxy/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Installing via PyPI

The stable version of the package is available on the PyPI repository. You can install it using the following command:

# Option 1: With uv (recommended)
uv tool install mcp-proxy

# Option 2: With pipx (alternative)
pipx install mcp-proxy

Once installed, you can run the server using the `mcp-proxy` command. See configuration options for each mode above.

Installing via Github repository (latest)

The latest version of the package can be installed from the git repository using the following command:

uv tool install git+https://github.com/sparfenyuk/mcp-proxy

> [!NOTE] > If you have already installed the server, you can update it using `uv tool upgrade --reinstall` command.

> [!NOTE] > If you want to delete the server, use the `uv tool uninstall mcp-proxy` command.

Installing as container

Starting from version 0.3.2, it's possible to pull and run the corresponding container image. Release images are published to GHCR and Docker Hub as multi-platform manifests for `linux/amd64` and `linux/arm64`; Docker selects the matching image for the host architecture automatically.

docker run --rm -t ghcr.io/sparfenyuk/mcp-proxy:v0.12.0 --help
docker run --rm -t sparfenyuk/mcp-proxy:v0.12.0 --help

Troubleshooting

- **Problem**: Claude Desktop can't start the server: ENOENT code in the logs

**Solution**: Try to use the full path to the binary. To do so, open a terminal and run the command`which mcp-proxy` ( macOS, Linux) or `where.exe mcp-proxy` (Windows). Then, use the output path as a value for 'command' attribute:

    "fetch": {
      "command": "/full/path/to/bin/mcp-proxy",
      "args": [
        "http://localhost:8932/sse"
      ]
    }

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 553 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # mcp-proxy
  2. ![GitHub License](https://img.shields.io/github/license/sparfenyuk/mcp-proxy)
  3. ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mcp-proxy)
  4. ![PyPI - Downloads](https://img.shields.io/pypi/dm/mcp-proxy)
  5. [![codecov](https://codecov.io/gh/sparfenyuk/mcp-proxy/graph/badge.svg?token=31VV9L7AZQ)](https://codecov.io/gh/sparfenyuk/mcp-proxy)
  6. - [mcp-proxy](#mcp-proxy)
  7. - [About](#about)
  8. - [1. stdio to SSE/StreamableHTTP](#1-stdio-to-ssestreamablehttp)
  9. - [1.1 Configuration](#11-configuration)
  10. - [1.2 Example usage](#12-example-usage)
  11. - [2. SSE to stdio](#2-sse-to-stdio)
  12. - [2.1 Configuration](#21-configuration)
  13. - [2.2 Example usage](#22-example-usage)
  14. - [Named Servers](#named-servers)
  15. - [Installation](#installation)
  16. - [Installing via PyPI](#installing-via-pypi)
  17. - [Installing via Github repository (latest)](#installing-via-github-repository-latest)
  18. - [Installing as container](#installing-as-container)
  19. - [Troubleshooting](#troubleshooting)
  20. - [Extending the container image](#extending-the-container-image)
  21. - [Docker Compose Setup](#docker-compose-setup)
  22. - [Command line arguments](#command-line-arguments)
  23. - [Example config file](#example-config-file)
  24. - [Testing](#testing)
  25. ## About
  26. The `mcp-proxy` is a tool that lets you switch between server transports. There are two supported modes:
  27. 1. stdio to SSE/StreamableHTTP
  28. 2. SSE to stdio
  29. ## 1. stdio to SSE/StreamableHTTP
  30. Run a proxy server from stdio that connects to a remote SSE server.
  31. This mode allows clients like Claude Desktop to communicate to a remote server over SSE even though it is not supported
  32. natively.
  33. ```mermaid
  34. graph LR
  35. A["Claude Desktop"] <--> |stdio| B["mcp-proxy"]
  36. B <--> |SSE| C["External MCP Server"]
  37. style A fill:#ffe6f9,stroke:#333,color:black,stroke-width:2px
  38. style B fill:#e6e6ff,stroke:#333,color:black,stroke-width:2px
  39. style C fill:#e6ffe6,stroke:#333,color:black,stroke-width:2px
  40. ```
  41. ### 1.1 Configuration
  42. This mode requires providing the URL of the MCP Server's SSE endpoint as the program’s first argument. If the server uses Streamable HTTP transport, make sure to enforce it on the `mcp-proxy` side by passing `--transport=streamablehttp`.
  43. When the proxy is a **Streamable HTTP client**, it bounds the final MCP session-termination `DELETE` request, including reading its response body, to five seconds. After cancellation or timeout, closing a received response gets a shielded, cooperative grace of up to one second; cleanup code that ignores cancellation can take longer. Graceful CLI teardown after SIGINT requires Python 3.11+; on Python 3.10, SIGINT may interrupt the event loop before the final `DELETE` is sent ([asyncio runner documentation](https://docs.python.org/3.11/library/asyncio-runner.html#handling-keyboard-interruption)). This limit applies only to that termination operation; normal `GET` streams and `POST` tool calls retain their usual HTTP timeouts. It is specific to reverse-client mode and does not change the stateful/stateless behavior of proxied HTTP servers.
  44. In reverse Streamable HTTP mode, an HTTP `404` on a `POST` for an established upstream session marks that session lost. The operation that received the `404` is never retried; its failure follows the existing proxy handling, and the server may already have applied it. A later explicit request may use a replacement session only when its complete initialization handshake matches the original. The proxy does not restore subscriptions, logging levels, or other upstream session-local state; after stateful resource or logging operations, or when the handshake changes, it refuses later requests and the MCP client must restart. Progress notifications are sent only to the current healthy session and are not buffered or replayed.
  45. Arguments
  46. | Name | Required | Description | Example |
  47. | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
  48. | `command_or_url` | Yes | The MCP server SSE endpoint to connect to | http://example.io/sse |
  49. | `--headers` | No | Headers to use for the MCP server SSE connection | Authorization 'Bearer my-secret-access-token' |
  50. | `--transport` | No | Decides which transport protocol to use when connecting to an MCP server. Can be either 'sse' or 'streamablehttp' | streamablehttp |
  51. | `--client-id` | No | OAuth2 client ID for authentication | your_client_id |
  52. | `--client-secret`| No | OAuth2 client secret for authentication | your_client_secret |
  53. | `--token-url` | No | OAuth2 token endpoint URL for authentication | https://auth.example.com/oauth/token |
  54. | `--username` | No | Username for authentication | user |
  55. | `--password` | No | Password for authentication | password |
  56. | `--digest` | No | Use digest authentication | |
  57. Environment Variables
  58. | Name | Required | Description | Example |
  59. | ------------------ | -------- | ---------------------------------------------------------------------------- | ---------- |
  60. | `API_ACCESS_TOKEN` | No | Can be used instead of `--headers Authorization 'Bearer <API_ACCESS_TOKEN>'` | YOUR_TOKEN |
  61. ### 1.2 Example usage
  62. `mcp-proxy` is supposed to be started by the MCP Client, so the configuration must be done accordingly.
  63. For Claude Desktop, the configuration entry can look like this:
  64. ```json
  65. {
  66. "mcpServers": {
  67. "mcp-proxy": {
  68. "command": "mcp-proxy",
  69. "args": [
  70. "http://example.io/sse"
  71. ],
  72. "env": {
  73. "API_ACCESS_TOKEN": "access-token"
  74. }
  75. }
  76. }
  77. }
  78. ```
  79. Closing the client's stdin disconnects the remote session and cancels connection setup, initialization, and active
  80. requests. Queued input is abandoned. Each input frame is limited to 4 MiB of UTF-8 wire payload bytes, excluding
  81. CR/LF delimiters. At most 4 MiB and 128 frames may be admitted but not yet consumed; empty and malformed frames count
  82. toward the frame limit. Exceeding either limit exits with an error instead of silently dropping input. These are
  83. admission limits, not an exact memory limit, because decoded text and protocol objects use additional memory.
  84. The client must read or close stdout. A full, unread stdout pipe can prevent process exit. A cancelled blocking stdin
  85. read may leave one daemon thread and its private descriptor until the read returns or the process exits. The helper
  86. supports one active CLI lifespan per process.
  87. ## 2. SSE to stdio
  88. Run a proxy server exposing a SSE server that connects to a local stdio server.
  89. This allows remote connections to the local stdio server. The `mcp-proxy` opens a port to listen for SSE requests,
  90. spawns a local stdio server that handles MCP requests.
  91. ```mermaid
  92. graph LR
  93. A["LLM Client"] <-->|SSE| B["mcp-proxy"]
  94. B <-->|stdio| C["Local MCP Server"]
  95. style A fill:#ffe6f9,stroke:#333,color:black,stroke-width:2px
  96. style B fill:#e6e6ff,stroke:#333,color:black,stroke-width:2px
  97. style C fill:#e6ffe6,stroke:#333,color:black,stroke-width:2px
  98. ```
  99. ### 2.1 Configuration
  100. Configure the HTTP server with `--host` and `--port`; the defaults are `127.0.0.1` and an available port. A wildcard
  101. bind such as `0.0.0.0` requires `--allowed-host` entries for the Host authorities clients will use. These host checks
  102. and CORS settings do not authenticate callers by default. `--headers` and `API_ACCESS_TOKEN` authenticate upstream
  103. client requests; they do not authenticate callers of this server.
  104. To require inbound authentication, set `MCP_PROXY_AUTH_TOKEN` or pass `--auth-bearer-token TOKEN`. An explicit CLI
  105. value takes precedence over the environment variable. Prefer the environment variable because local process tools may
  106. show command-line arguments. With neither value set, the server keeps its unauthenticated default. When enabled, every
  107. HTTP request needs `Authorization: Bearer TOKEN`, including requests to `/status`, `/healthz`, SSE, StreamableHTTP,
  108. and named-server routes. Health probes must send the token. Configured CORS preflight requests still work without a
  109. token; ordinary `OPTIONS` requests require one. Host and Origin checks continue to apply.
  110. `MCP_PROXY_AUTH_TOKEN` is removed from child processes when `--pass-environment` copies the proxy environment.
  111. Values passed explicitly with `--env` or a named-server configuration remain part of that server's environment.
  112. This shared token does not provide user identity or roles and does not make the proxy compliant with MCP OAuth.
  113. Use TLS or a trusted network/reverse proxy when exposing the server beyond a trusted local network.
  114. The deprecated `--sse-host` and `--sse-port` options are ineffective; use `--host` and `--port` instead. Additional
  115. environment variables can be passed to the local stdio server using `--env`. Put local server arguments after the `--` separator.
  116. Startup logs list the SSE and StreamableHTTP endpoints for each configured backend. With `--port=0`, they list endpoint
  117. paths because Uvicorn selects the actual port during startup; combine each path with Uvicorn's listening address.
  118. Arguments
  119. | Name | Required | Description | Example |
  120. | ------------------------------------ | -------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------- |
  121. | `command_or_url` | Yes | The command to spawn the MCP stdio server | uvx mcp-server-fetch |
  122. | `--port` | No, random available | The MCP server port to listen on | 8080 |
  123. | `--host` | No, `127.0.0.1` by default | Host IP address to bind. Wildcard binds require explicit `--allowed-host` authorities. | 0.0.0.0 |
  124. | `--auth-bearer-token` | No | Require one shared Bearer token on every inbound HTTP request. Prefer `MCP_PROXY_AUTH_TOKEN`. | `<TOKEN>` |
  125. | `--allowed-host` | No | Additional trusted Host authority; repeat for each hostname/IP and port clients use. | --allowed-host mcp.example.com:8080 |
  126. | `--env` | No | Additional environment variables to pass to the MCP stdio server. Can be used multiple times. | FOO BAR |
  127. | `--cwd` | No | The working directory to pass to the MCP stdio server process. | /tmp |
  128. | `--pass-environment` | No | Pass through all environment variables when spawning the server | --no-pass-environment |
  129. | `--allow-origin` | No | Allowed origins for the SSE server. Can be used multiple times. Default is no CORS allowed. | --allow-origin "\*" |
  130. | `--expose-header` | No | Headers added to `Access-Control-Expose-Headers`. Can be used multiple times. Defaults to `mcp-session-id`. | --expose-header Custom-Header |
  131. | `--initialization-timeout SECONDS` | No | Deadline for each stdio server initialization; default is unlimited. Cleanup may take additional time. | --initialization-timeout 30 |
  132. | `--stateless` | No | Enable stateless mode for streamable http transports. Default is False | --no-stateless |
  133. | `--named-server NAME COMMAND_STRING` | No | Defines a named stdio server. | --named-server fetch 'uvx mcp-server-fetch' |
  134. | `--named-server-config FILE_PATH` | No | Path to a JSON file defining named stdio servers. | --named-server-config /path/to/servers.json |
  135. | `--sse-port` (deprecated) | No | Ineffective; use `--port` instead. | — |
  136. | `--sse-host` (deprecated) | No | Ineffective; use `--host` instead. | — |
  137. ### 2.2 Example usage
  138. To start the `mcp-proxy` server that listens on port 8080 and connects to the local MCP server:
  139. ```bash
  140. # Start the MCP server behind the proxy
  141. mcp-proxy uvx mcp-server-fetch
  142. # Start the MCP server behind the proxy with a custom port
  143. mcp-proxy --port=8080 uvx mcp-server-fetch
  144. # Start the MCP server behind the proxy with a custom host and port
  145. mcp-proxy --host=0.0.0.0 --port=8080 --allowed-host mcp.example.com:8080 uvx mcp-server-fetch
  146. # Replace mcp.example.com:8080 with the hostname/IP and port clients send in their Host header.
  147. # Start the MCP server behind the proxy with a custom user agent
  148. # Note that the `--` separator is used to separate the `mcp-proxy` arguments from the `mcp-server-fetch` arguments
  149. mcp-proxy --port=8080 -- uvx mcp-server-fetch --user-agent=YourUserAgent
  150. # Start multiple named MCP servers behind the proxy
  151. mcp-proxy --port=8080 --named-server fetch 'uvx mcp-server-fetch' --named-server fetch2 'uvx mcp-server-fetch'
  152. # Start multiple named MCP servers using a configuration file
  153. mcp-proxy --port=8080 --named-server-config ./servers.json
  154. # Start the MCP server with CORS enabled and custom exposed headers
  155. mcp-proxy --port=8080 --allow-origin='*' --expose-header Custom-Header uvx mcp-server-fetch
  156. ```
  157. ## Named Servers
  158. - `NAME` is used in the URL path `/servers/NAME/`.
  159. - `COMMAND_STRING` is the command to start the server (e.g., 'uvx mcp-server-fetch').
  160. - Can be used multiple times.
  161. - This argument is ignored if `--named-server-config` is used.
  162. - `FILE_PATH` - If provided, this is the exclusive source for named servers, and `--named-server` CLI arguments are ignored.
  163. If a default server is specified (the `command_or_url` argument without `--named-server` or `--named-server-config`), it will be accessible at the root paths (e.g., `http://127.0.0.1:8080/sse`).
  164. Named servers (whether defined by `--named-server` or `--named-server-config`) will be accessible under `/servers/<server-name>/` (e.g., `http://127.0.0.1:8080/servers/fetch1/sse`).
  165. The `/status` endpoint provides global status. Its `server_instances` keys normally use the configured
  166. named-server names and `default` for the positional server. If both a positional server and a named
  167. server called `default` are configured, all entries use route keys instead: `/` for the positional
  168. server and `/servers/<name>` for named servers. This keeps both instances distinct without reserving
  169. a configured name.
  170. If a named server fails with a spawn-stage operating-system error other than `TimeoutError`, an MCP
  171. initialization error, an initialization timeout, or stdout EOF observed before activation, `mcp-proxy`
  172. marks it as `failed` in `/status` and continues with the remaining named servers. Failed servers have
  173. no routes or advertised endpoints. Other startup failures, cleanup failures, and failures in the
  174. positional server remain fatal. Startup exits with an error if none of the configured servers starts.
  175. **JSON Configuration File Format for `--named-server-config`:**
  176. The JSON file should follow this structure:
  177. ```json
  178. {
  179. "mcpServers": {
  180. "fetch": {
  181. "disabled": false,
  182. "timeout": 60,
  183. "command": "uvx",
  184. "args": [
  185. "mcp-server-fetch"
  186. ],
  187. "transportType": "stdio"
  188. },
  189. "github": {
  190. "timeout": 60,
  191. "command": "npx",
  192. "args": [
  193. "-y",
  194. "@modelcontextprotocol/server-github"
  195. ],
  196. "env": {
  197. "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
  198. },
  199. "transportType": "stdio"
  200. }
  201. }
  202. }
  203. ```
  204. - `mcpServers`: A dictionary where each key is the server name (used in the URL path, e.g., `/servers/fetch/`) and the value is an object defining the server.
  205. - `command`: (Required) The command to execute for the stdio server.
  206. - `args`: (Optional) A list of arguments for the command. Defaults to an empty list.
  207. - `enabled`: (Optional) If `false`, this server definition will be skipped. Defaults to `true`.
  208. - `timeout` and `transportType`: These fields are present in standard MCP client configurations but are currently **ignored** by `mcp-proxy` when loading named servers. The transport type is implicitly "stdio".
  209. ## Installation
  210. ### Installing via PyPI
  211. The stable version of the package is available on the PyPI repository. You can install it using the following command:
  212. ```bash
  213. # Option 1: With uv (recommended)
  214. uv tool install mcp-proxy
  215. # Option 2: With pipx (alternative)
  216. pipx install mcp-proxy
  217. ```
  218. Once installed, you can run the server using the `mcp-proxy` command. See configuration options for each mode above.
  219. ### Installing via Github repository (latest)
  220. The latest version of the package can be installed from the git repository using the following command:
  221. ```bash
  222. uv tool install git+https://github.com/sparfenyuk/mcp-proxy
  223. ```
  224. > [!NOTE]
  225. > If you have already installed the server, you can update it using `uv tool upgrade --reinstall` command.
  226. > [!NOTE]
  227. > If you want to delete the server, use the `uv tool uninstall mcp-proxy` command.
  228. ### Installing as container
  229. Starting from version 0.3.2, it's possible to pull and run the corresponding container image.
  230. Images are published to GHCR and Docker Hub as multi-platform manifests for `linux/amd64` and `linux/arm64`;
  231. Docker selects the matching image for the host architecture automatically.
  232. The runtime image flavors are:
  233. | Flavor | Base | Tools |
  234. | --- | --- | --- |
  235. | `alpine` | Python 3.13 on Alpine Linux (musl) | `uv`, `uvx` |
  236. | `debian` | Python 3.13 on Debian Bookworm (glibc) | `uv`, `uvx` |
  237. | `debian-node` | Debian Bookworm (glibc) | `uv`, `uvx`, Node.js 24, `npm`, `npx` |
  238. The unsuffixed tags and `-alpine` tags select the Alpine image. For a release
  239. tag such as `vX.Y.Z`, the Debian images use `vX.Y.Z-debian` and
  240. `vX.Y.Z-debian-node`; main-branch commit tags use the matching
  241. `commit-<short-sha>-debian` and `commit-<short-sha>-debian-node` forms. New
  242. flavors are available only for builds made after this change is released;
  243. existing tags are not rebuilt. The existing automatic `latest` release alias
  244. continues to select Alpine. Debian flavors have no moving alias.
  245. Choose Debian when a Python package needs glibc. Choose `debian-node` when the
  246. MCP server needs Node.js tools; it can run `npx` packages but does not bundle
  247. all possible server-specific system libraries. Installing tools with
  248. dependencies that are not already cached still requires network access.
  249. ```bash
  250. docker run --rm -t ghcr.io/sparfenyuk/mcp-proxy:v0.12.0 --help
  251. docker run --rm -t sparfenyuk/mcp-proxy:v0.12.0 --help
  252. ```
  253. ### Troubleshooting
  254. - **Problem**: Claude Desktop can't start the server: ENOENT code in the logs
  255. **Solution**: Try to use the full path to the binary. To do so, open a terminal and run the command`which mcp-proxy` (
  256. macOS, Linux) or `where.exe mcp-proxy` (Windows). Then, use the output path as a value for 'command' attribute:
  257. ```json
  258. "fetch": {
  259. "command": "/full/path/to/bin/mcp-proxy",
  260. "args": [
  261. "http://localhost:8932/sse"
  262. ]
  263. }
  264. ```
  265. ## Extending a container image
  266. The `debian-node` flavor includes Node.js, `npm`, and `npx`. For other
  267. operating-system packages, extend a flavor with that distribution's package
  268. manager. Keep Python virtual environments on the same libc family as their
  269. build stage.
  270. ```Dockerfile
  271. # file: mcp-proxy.Dockerfile
  272. FROM ghcr.io/sparfenyuk/mcp-proxy:vX.Y.Z-alpine
  273. RUN apk add --no-cache curl
  274. ENV UV_PYTHON_PREFERENCE=only-system
  275. ```
  276. Build and run the custom image:
  277. ```bash
  278. docker build -f mcp-proxy.Dockerfile -t mcp-proxy-custom .
  279. docker run --rm -p 127.0.0.1:8080:8080 mcp-proxy-custom \
  280. --host=0.0.0.0 --port=8080 --allowed-host 127.0.0.1:8080 \
  281. -- uvx mcp-server-fetch
  282. ```
  283. The first `uvx` or `npx` launch needs network access to download a package that is not already cached.
  284. When exposing the proxy beyond a local test, continue to configure `--allowed-host`
  285. and allowed origins for the client-facing address. `--pass-environment` controls
  286. which host environment values reach spawned server processes; use it only when needed.
  287. To check a locally built image, run the opt-in container tests:
  288. ```bash
  289. docker build -t mcp-proxy:flavors-alpine .
  290. MCP_PROXY_TEST_IMAGE=mcp-proxy:flavors-alpine MCP_PROXY_TEST_FLAVOR=alpine uv run --frozen pytest -q tests/test_container_image.py
  291. docker build -f Dockerfile.debian --target debian -t mcp-proxy:flavors-debian .
  292. MCP_PROXY_TEST_IMAGE=mcp-proxy:flavors-debian MCP_PROXY_TEST_FLAVOR=debian uv run --frozen pytest -q tests/test_container_image.py
  293. docker build -f Dockerfile.debian --target debian-node -t mcp-proxy:flavors-debian-node .
  294. MCP_PROXY_TEST_IMAGE=mcp-proxy:flavors-debian-node MCP_PROXY_TEST_FLAVOR=debian-node uv run --frozen pytest -q tests/test_container_image.py
  295. ```
  296. These tests disable container network access, run a local wheel through `uvx`,
  297. launch an MCP server through `uv`, and exercise a local `npx` package. Flavor
  298. checks are skipped when `MCP_PROXY_TEST_FLAVOR` is unset; all container tests
  299. are skipped when `MCP_PROXY_TEST_IMAGE` is unset.
  300. ## Docker Compose Setup
  301. With the custom Dockerfile, you can define a service in your Docker Compose file:
  302. ```yaml
  303. services:
  304. mcp-proxy-custom:
  305. build:
  306. context: .
  307. dockerfile: mcp-proxy.Dockerfile
  308. network_mode: host
  309. restart: unless-stopped
  310. ports:
  311. - 8096:8096
  312. command: "--pass-environment --host=0.0.0.0 --port=8096 --allowed-host mcp.example.com:8096 uvx mcp-server-fetch"
  313. ```
  314. > [!NOTE]
  315. > Don't forget to set `--pass-environment` argument, otherwise you'll end up with the error "No interpreter found in
  316. > managed installations or search path"
  317. > Replace `mcp.example.com:8096` with the hostname/IP and port clients send in their `Host` header.
  318. ## Command line arguments
  319. ```bash
  320. usage: mcp-proxy [-h] [--version] [-H KEY VALUE]
  321. [--transport {sse,streamablehttp}] [--verify-ssl [VALUE]]
  322. [--no-verify-ssl] [-e KEY VALUE] [--cwd CWD]
  323. [--client-id CLIENT_ID] [--client-secret CLIENT_SECRET] [--token-url TOKEN_URL]
  324. [--pass-environment | --no-pass-environment]
  325. [--log-level LEVEL] [--debug | --no-debug]
  326. [--named-server NAME COMMAND_STRING]
  327. [--named-server-config FILE_PATH] [--port PORT] [--host HOST]
  328. [--stateless | --no-stateless] [--sse-port SSE_PORT]
  329. [--sse-host SSE_HOST]
  330. [--allow-origin ALLOW_ORIGIN [ALLOW_ORIGIN ...]]
  331. [--allowed-host HOST]
  332. [--expose-header HEADER]
  333. [command_or_url] [args ...]
  334. Start the MCP proxy in one of two possible modes: as a client or a server.
  335. positional arguments:
  336. command_or_url Command or URL to connect to. When a URL, will run an SSE/StreamableHTTP client. Otherwise, if --named-server is not used, this will be the command for the default stdio client. If --named-server is used, this argument is ignored for stdio mode unless no default server is desired. See corresponding options for more details.
  337. options:
  338. -h, --help show this help message and exit
  339. --version Show the version and exit
  340. SSE/StreamableHTTP client options:
  341. -H, --headers KEY VALUE
  342. Headers to pass to the SSE server. Can be used multiple times.
  343. --transport {sse,streamablehttp}
  344. The transport to use for the client. Default is SSE.
  345. --verify-ssl [VALUE] Control SSL verification when acting as a client. Use without a value to force verification, pass 'false' to disable, or provide a path to a PEM bundle.
  346. --no-verify-ssl Disable SSL verification (alias for --verify-ssl false).
  347. --client-id CLIENT_ID
  348. OAuth2 client ID for authentication
  349. --client-secret CLIENT_SECRET
  350. OAuth2 client secret for authentication
  351. --token-url TOKEN_URL
  352. OAuth2 token URL for authentication
  353. --username USERNAME Username for authentication
  354. --password PASSWORD Password for authentication
  355. --digest Use digest authentication
  356. stdio client options:
  357. args Any extra arguments to the command to spawn the default server. Ignored if only named servers are defined.
  358. -e, --env KEY VALUE Environment variables used when spawning the default server. Can be used multiple times. For named servers, environment is inherited or passed via --pass-environment.
  359. --cwd CWD The working directory to use when spawning the default server process. Named servers inherit the proxy's CWD.
  360. --pass-environment, --no-pass-environment
  361. Pass through all environment variables when spawning all server processes.
  362. --log-level LEVEL Set the log level. Default is INFO.
  363. --debug, --no-debug Enable debug mode with detailed logging output. Equivalent to --log-level DEBUG. If both --debug and --log-level are provided, --debug takes precedence.
  364. --named-server NAME COMMAND_STRING
  365. Define a named stdio server. NAME is for the URL path /servers/NAME/. COMMAND_STRING is a single string with the command and its arguments (e.g., 'uvx mcp-server-fetch --timeout 10'). These servers inherit the proxy's CWD and environment from --pass-environment.
  366. --named-server-config FILE_PATH
  367. Path to a JSON configuration file for named stdio servers. If provided, this will be the exclusive source for named server definitions, and any --named-server CLI arguments will be ignored.
  368. SSE server options:
  369. --port PORT Port to expose an SSE server on. Default is a random port
  370. --host HOST Host to expose an SSE server on. Default is 127.0.0.1
  371. --initialization-timeout SECONDS
  372. Maximum time to initialize each stdio server. By default, wait indefinitely.
  373. A timeout fails proxy startup and does not limit tool calls. Cleanup may take additional time.
  374. --stateless, --no-stateless
  375. Enable stateless mode for streamable http transports. Default is False
  376. --sse-port SSE_PORT (deprecated and ineffective; use --port)
  377. --sse-host SSE_HOST (deprecated and ineffective; use --host)
  378. --allow-origin ALLOW_ORIGIN [ALLOW_ORIGIN ...]
  379. Allowed origins for the SSE server. Can be used multiple times. Default is no CORS allowed.
  380. --allowed-host HOST Additional trusted Host authority. Can be used multiple times.
  381. --expose-header HEADER
  382. Headers to expose via Access-Control-Expose-Headers. Defaults to 'Mcp-Session-Id'. Can be used multiple times.
  383. HTTP server requests are checked against trusted Host authorities before reaching routes. Loopback hostnames and IPs are trusted by default; a non-wildcard `--host` also trusts that bind address. A wildcard bind does not trust arbitrary Host values. Add the public hostname or reverse-proxy Host with `--allowed-host`, repeating the option for each authority (for example, `--allowed-host mcp.example.com --allowed-host mcp.example.com:8443`). A terminal `:*` may be used for an authority that accepts any port.
  384. Raw Uvicorn HTTP access-log lines are disabled because SSE session IDs can appear in request query strings.
  385. Host and browser Origin are separate checks. `--allow-origin '*'` allows browser Origins but does not bypass Host validation. Native clients that omit Origin remain supported. These checks do not authenticate callers; protect publicly reachable deployments with network controls or an authenticated reverse proxy.
  386. Examples:
  387. mcp-proxy http://localhost:8080/sse
  388. mcp-proxy --no-verify-ssl https://server.local/sse
  389. mcp-proxy --transport streamablehttp http://localhost:8080/mcp
  390. mcp-proxy --transport streamablehttp --username user --password pass https://server.local/mcp
  391. mcp-proxy --headers Authorization 'Bearer YOUR_TOKEN' http://localhost:8080/sse
  392. mcp-proxy --client-id CLIENT_ID --client-secret CLIENT_SECRET --token-url https://auth.example.com/token http://localhost:8080/sse
  393. mcp-proxy --port 8080 -- your-command --arg1 value1 --arg2 value2
  394. mcp-proxy --named-server fetch 'uvx mcp-server-fetch' --port 8080
  395. mcp-proxy your-command --port 8080 -e KEY VALUE -e ANOTHER_KEY ANOTHER_VALUE
  396. mcp-proxy your-command --port 8080 --allow-origin='*'
  397. mcp-proxy your-command --port 8080 --allow-origin='*' --expose-header Custom-Header
  398. ```
  399. ### Example config file
  400. ```json
  401. {
  402. "mcpServers": {
  403. "fetch": {
  404. "enabled": true,
  405. "timeout": 60,
  406. "command": "uvx",
  407. "args": [
  408. "mcp-server-fetch"
  409. ],
  410. "transportType": "stdio"
  411. },
  412. "github": {
  413. "timeout": 60,
  414. "command": "npx",
  415. "args": [
  416. "-y",
  417. "@modelcontextprotocol/server-github"
  418. ],
  419. "env": {
  420. "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
  421. },
  422. "transportType": "stdio"
  423. }
  424. }
  425. }
  426. ```
  427. ## Testing
  428. Check the `mcp-proxy` server by running it with the `mcp-server-fetch` server. You can use
  429. the [inspector tool](https://modelcontextprotocol.io/docs/tools/inspector) to test the target server.
  430. ```bash
  431. # Run the stdio server called mcp-server-fetch behind the proxy over SSE
  432. mcp-proxy --port=8080 uvx mcp-server-fetch &
  433. # Connect to the SSE proxy server spawned above using another instance of mcp-proxy given the URL of the SSE server
  434. mcp-proxy http://127.0.0.1:8080/sse
  435. # Send CTRL+C to stop the second server
  436. # Bring the first server to the foreground
  437. fg
  438. # Send CTRL+C to stop the first server
  439. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.