Broxy acts as a single MCP endpoint that aggregates and fronts multiple upstream MCP servers. It lets you mix and expose only the capabilities needed for a given agent or workflow, providing a stable surface even as underlying presets change. You can connect clients such as ChatGPT and other MCP-enabled tools to local MCP servers via STDIO, HTTP, SSE, or WebSocket, enabling private tools and resources to be used in a secure, centralized manner. The built-in capabilities include dynamic client registration with OAuth, secure remote connectivity, and the ability to auto-configure common clients for quick adoption. In practice, you run a Broxy CLI proxy instance, point it at a preset that defines which tools and prompts to expose, and then connect your client to the Streamable HTTP endpoint or the local STDIO channel. The SSE endpoint also provides a session-based path for forwarding JSON-RPC messages between clients and the MCP surface.

Prerequisites:

• Java Runtime Environment (JRE) 11+ or JDK 11+ installed on your system
• Git to clone the repository (or you can work from a fork)
• Optional: Gradle wrapper dependencies (the project uses Gradle to build the CLI jar)

Step-by-step installation:

1. Clone the repository git clone https://github.com/qent/broxy.git cd broxy

2. Build the CLI jar (as documented by the project) ./gradlew :cli:shadowJar

   The generated jar will be at cli/build/libs/broxy-cli.jar

3. Run the proxy (example using STDIO inbound) java -jar cli/build/libs/broxy-cli.jar proxy
   --preset-id <preset-id>
   --config-dir ~/.config/broxy
   --inbound stdio

4. Optional: run the proxy to expose Streamable HTTP / SSE java -jar cli/build/libs/broxy-cli.jar proxy
   --preset-id <preset-id>
   --config-dir ~/.config/broxy
   --inbound http
   --url http://localhost:3335/mcp

Notes:

• Replace <preset-id> with the actual preset you intend to use.
• The config directory defaults to ~/.config/broxy if not provided.
• Ensure network ports (e.g., 3335 for HTTP) are open if you expect remote access.

Tips and common considerations:

• The Broxy CLI jar acts as the MCP surface; you can swap presets without clients needing to refresh capabilities.
• When using OAuth dynamic client registration, ensure your upstreams expose the necessary OAuth metadata and that Broxy is permitted to register clients dynamically.
• If you run behind a reverse proxy or via a remote gateway, make sure the /mcp endpoint is reachable and the WebSocket/SSE endpoints are properly proxied.
• Environment variables shown in the mcp_config can be customized to fit your deployment environment; use them to document required values for teams.
• The default flows expect a valid preset and corresponding mcp.json in the config directory; ensure those files exist before starting the server.