MCP Proxy Hub

An MCP proxy server that aggregates and serves multiple MCP resource servers through a single interface. This server acts as a central hub that can:

- Connect to and manage multiple MCP resource servers
- Expose their combined capabilities through a unified interface
- Handle routing of requests to appropriate backend servers
- Aggregate responses from multiple sources

- Discover and connect to multiple MCP resource servers
- Aggregate resources from all connected servers
- Maintain consistent URI schemes across servers
- Handle resource routing and resolution

- Expose tools from all connected servers with server name prefixes
- Apply tool filtering based on configuration (exposedTools/hiddenTools)
- Support tool name remapping via configuration
- Route tool calls to appropriate backend servers

-

Define compound tools that combine functionality from multiple servers

Execute subtools using server and tool name specifications

Provide detailed documentation through tool descriptions

Specify execution with a standardized format:

{ "server": "server_name", "tool": "tool_name", "args": { // Tool-specific arguments } }

- Automatically expand environment variables in tool arguments
- Automatically replace sensitive values with variable references in responses
- Configure which variables should be expanded/unexpanded via configuration
- Support for both global (all servers) and server-specific environment variables
- Server-specific variables take precedence over global variables with the same name
- Each variable can be independently configured for expansion and unexpansion
- Environment variables are only expanded when using the${VARIABLE_NAME}syntax (e.g.,${API_KEY}). The$VARIABLE_NAMEsyntax is not supported.
- Secure handling of sensitive information like API keys

- Aggregate prompts from all connected servers
- Route prompt requests to appropriate backends
- Handle multi-server prompt responses

The server requires a JSON configuration file that specifies the MCP servers to connect to. Copy the example config(config.example.json) and modify it for your needs:

"envVars": [ { "name": "API_KEY", "value": "my-api-key", "expand": true, "unexpand": true }, { "name": "USER_ID", "value": "user123", "expand": true, "unexpand": false } ]

-

Array of environment variable configurations applied to all servers

Uses the same configuration format as server-specific envVars

Server-specific variables with the same name override global variables

Defined at the root level of the configuration file

"envVars": [ { "name": "GLOBAL_API_KEY", "value": "global-api-key", "expand": true, "unexpand": true }, { "name": "GLOBAL_ENV", "value": "production", "expand": true, "unexpand": false } ]

Controls how long the proxy hub waits for a downstream server to respond to a tool call (tools/call) or tool listing (tools/list) before aborting.

- Top-leveltimeout: Global default in seconds applied to all servers.
- Per-servertimeout(inside eachmcpServers[name]): Overrides the global value for that server.
- 0: Disables the timeout for that scope (no upper bound).
- Unset: Falls back to the MCP SDK default (60 seconds).

Values whose millisecond conversion (timeout * 1000) exceeds2147483647ms (the maximum safesetTimeoutdelay) are capped to that ceiling. Negative,NaN, or non-number values are ignored and fall through to the next level with a warning.

{ "timeout": 30, "mcpServers": { "slow-server": { "command": "...", "timeout": 0 }, "fast-server": { "command": "...", "timeout": 5 } } }

Configure how the proxy hub itself is served via theserverTransportsection:

"serverTransport": { "type": "streamable-http", "port": 3006, "host": "0.0.0.0", "path": "/mcp", "auth": { "type": "bearer", "token": "your-secret-token" } }

- type: Transport type ("stdio", "sse", or "streamable-http")
- port: Port number for HTTP-based transports (default: 3006)
- host: Host to bind to (default: "0.0.0.0")
- path: URL path for Streamable HTTP endpoint (default: "/mcp")
- auth: Authentication configuration (optional)

- type: "bearer" (currently the only supported type)
- token: The bearer token required for authentication

Authentication can also be configured via theMCP_PROXY_AUTH_TOKENenvironment variable.

- tools:

- Object with custom tool names as keys
- Each tool hasdescriptionandsubtools
- subtoolsis keyed by server name and contains each server's tool list

- MCP_PROXY_CONFIG_PATH: Path to the configuration file
- MCP_PROXY_LOG_DIRECTORY_PATH: Path to the log directory
- MCP_PROXY_LOG_LEVEL: Log level ("debug" or "info")
- MCP_PROXY_AUTH_TOKEN: Bearer token for authenticating incoming requests to the proxy server
- MCP_PROXY_PATH: URL path for Streamable HTTP endpoint (default: "/mcp")
- KEEP_SERVER_OPEN: Whether to keep the server open after client disconnection in SSE mode (set to "1" to enable)
- PORT: Port for the SSE/Streamable HTTP server (default: 3006)
- HOST: Host to bind for the HTTP server (default: "0.0.0.0")

# Stdio npm run dev # SSE npm run dev:sse # Streamable HTTP npm run dev:http

The CLI provides two modes of operation for interacting with the MCP Proxy Hub.

You can execute commands directly from your terminal. This is useful for scripting and automation.

mcp-proxy-hub-cli call <toolName> [args...]

- toolName: The name of the tool to call.
- args: Arguments for the tool inkey=valueformat.
- --output-dir <dir>or-o <dir>: Save the output to a directory.

mcp-proxy-hub-cli call my_tool param1=value1 -o output

If you run the CLI without any arguments, it will start in interactive mode. This provides a shell-like interface for running commands.

Once in interactive mode, you can use the following commands:

- list: List available tools.
- call <toolName> [args...]: Call a tool with arguments.
- exit: Exit the interactive session.

To use with Claude Desktop, add the server config:

On MacOS:~/Library/Application Support/Claude/claude_desktop_config.jsonOn Windows:%APPDATA%/Claude/claude_desktop_config.json

{ "mcpServers": { "mcp-proxy-hub": { "command": "/path/to/mcp-proxy-hub/build/index.js", "env": { "MCP_PROXY_CONFIG_PATH": "/absolute/path/to/your/config.json", "KEEP_SERVER_OPEN": "1" } } } }

KEEP_SERVER_OPENwill keep the SSE running even if a client disconnects. This is useful when multiple clients connect to the MCP proxy.

Since MCP servers communicate over stdio, debugging can be challenging. We recommend using theMCP Inspector, which is available as a package script:

A lightweight server exposing Axone's capabilities through the Model-Context Protocol.