Labsco
ptbsare logo

MCP Proxy Server

โ˜… 194

from ptbsare

Aggregates multiple MCP resource servers into a single interface with stdio/sse support.

๐Ÿ”ฅ๐Ÿ”ฅ๐Ÿ”ฅ๐Ÿ”ฅโœ“ VerifiedAccount requiredAdvanced setup
#automation#scraping#devops#git#maps#security

MCP Proxy Server

็ฎ€ไฝ“ไธญๆ–‡

โœจ Key Features Highlight

  • ๐ŸŒ Web UI Management: Easily manage all connected MCP servers through an intuitive web interface (optional, requires enabling).
  • ๐Ÿ”ง Granular Tool Control: Enable or disable individual tools, and override names/descriptions via the Web UI.
  • ๐Ÿ›ก๏ธ Flexible Endpoint Authentication: Secure your HTTP-based endpoints (/sse, /mcp) with flexible authentication options (Authorization: Bearer <token> or X-API-Key: <key>).
  • ๐Ÿ”„ Robust Session Handling & Concurrency:
    • Improved SSE session handling for client reconnections (relying on server-sent endpoint events) and support for concurrent connections.
    • Streamable HTTP endpoint (/mcp) also supports concurrent client interactions.
  • ๐Ÿš€ Versatile MCP Operations (Server & Proxy):
    • Acts as a Proxy: Connects to and aggregates multiple backend MCP servers of various types (Stdio, SSE, Streamable HTTP).
    • Acts as a Server: Exposes these aggregated capabilities through its own Streamable HTTP (/mcp) and SSE (/sse) endpoints. Can also run in a pure Stdio mode.
  • โœจ Real-time Install Output: Monitor Stdio server installation progress (stdout/stderr) directly in the Web UI.
  • โœจ Web Terminal: Access a command-line terminal within the Admin UI for direct server interaction (optional, use with caution due to security risks).

This server acts as a central hub for Model Context Protocol (MCP) resource servers. It can:

  • Connect to and manage multiple backend MCP servers (Stdio, SSE, and Streamable HTTP types).
  • Expose their combined capabilities (tools, resources) through a single, unified SSE interface, a Streamable HTTP interface, or act as a single Stdio-based MCP server itself.
  • Handle routing of requests to the appropriate backend servers.
  • Aggregate responses if needed (though primarily acts as a proxy).
  • Support multiple simultaneous SSE client connections with optional API key authentication.

Features

Resource & Tool Management via Proxy

  • Discovers and connects to multiple MCP resource servers defined in config/mcp_server.json.
  • Aggregates tools and resources from all connected active servers.
  • Routes tool calls and resource access requests to the correct backend server.
  • Maintains consistent URI schemes.

โœจ Optional Web Admin UI (ENABLE_ADMIN_UI=true)

Provides a browser-based interface for managing the proxy server configuration and connected tools. Features include:

  • Server Configuration: View, add, edit, and delete server entries (mcp_server.json). Supports Stdio, SSE, and HTTP server types with relevant options (type, command, args, env, url, apiKey, bearerToken, install config).
  • Tool Configuration: View all tools discovered from active backend servers. Enable or disable specific tools. Override the display name and description for each tool (tool_config.json).
  • Live Reload: Apply server and tool configuration changes by triggering a configuration reload without needing to restart the entire proxy server process.
  • Stdio Server Installation: For Stdio servers, you can define installation commands in the configuration. The Admin UI allows you to:
    • Trigger the execution of these installation commands.
    • Monitor installation progress in real-time with live stdout and stderr output streamed directly to the UI.
  • Web Terminal: Access an integrated web-based terminal that provides shell access to the environment where the proxy server is running.
    • Security Warning: This feature grants significant access and should be used with extreme caution, especially if the admin interface is exposed.

Enhanced Reliability Features

The MCP Proxy Server includes features to improve its resilience and the reliability of interactions with backend MCP services, ensuring smoother operations and more consistent tool execution.

1. Error Propagation

The proxy server ensures that errors originating from backend MCP services are consistently propagated to the requesting client. These errors are formatted as standard JSON-RPC error responses, making it easier for clients to handle them uniformly.

2. SSE Tool Call Retry

When a tools/call operation is made to an SSE-based backend server, and the underlying connection is lost or experiences an error (including timeouts), the proxy server implements a retry mechanism.

Retry Mechanism: If an initial SSE tool call fails due to a connection error or timeout, the proxy will attempt to re-establish the connection to the SSE backend. If reconnection is successful, it will then retry the original tools/call request using an exponential backoff strategy, similar to HTTP and Stdio retries. This means the delay before each subsequent retry attempt increases exponentially, with a small amount of jitter (randomness) added.

Configuration: These settings are primarily controlled by environment variables. Values in config/mcp_server.json under the proxy object for these specific keys will be overridden by environment variables if set.

  • RETRY_SSE_TOOL_CALL (environment variable):

    • Set to "true" to enable retries for SSE tool calls.
    • Set to "false" to disable this feature.
    • Default Behavior: true (if the environment variable is not set, is empty, or is an invalid value).

  • SSE_TOOL_CALL_MAX_RETRIES (environment variable):

    • Specifies the maximum number of retry attempts after the initial failed attempt. For example, if set to "2", there will be one initial attempt and up to two retry attempts, totaling a maximum of three attempts.
    • Default Behavior: 2 (if the environment variable is not set, is empty, or is not a valid integer).

  • SSE_TOOL_CALL_RETRY_DELAY_BASE_MS (environment variable):

    • The base delay in milliseconds used in the exponential backoff calculation. The delay before the n-th retry (0-indexed) is roughly SSE_TOOL_CALL_RETRY_DELAY_BASE_MS * (2^n) + jitter.
    • Default Behavior: 300 (milliseconds) (if the environment variable is not set, is empty, or is not a valid integer).

Example (Environment Variables):

export RETRY_SSE_TOOL_CALL="true"
export SSE_TOOL_CALL_MAX_RETRIES="3"
export SSE_TOOL_CALL_RETRY_DELAY_BASE_MS="500"

3. HTTP Request Retry for Tool Calls

For tools/call operations directed to HTTP-based backend servers, the proxy implements a retry mechanism for connection errors (e.g., "failed to fetch", network timeouts).

Retry Mechanism: If an initial HTTP request fails due to a connection error, the proxy will retry the request using an exponential backoff strategy. This means the delay before each subsequent retry attempt increases exponentially, with a small amount of jitter (randomness) added to prevent thundering herd scenarios.

Configuration: These settings are primarily controlled by environment variables.

  • RETRY_HTTP_TOOL_CALL (environment variable):

    • Set to "true" to enable retries for HTTP tool calls.
    • Set to "false" to disable this feature.
    • Default Behavior: true (if the environment variable is not set, is empty, or is an invalid value).

  • HTTP_TOOL_CALL_MAX_RETRIES (environment variable):

    • Specifies the maximum number of retry attempts after the initial failed attempt. For example, if set to "2"๏ผŒthere will be one initial attempt and up to two retry attempts, totaling a maximum of three attempts.
    • Default Behavior: 2 (if the environment variable is not set, is empty, or is not a valid integer).

  • HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS (environment variable):

    • The base delay in milliseconds used in the exponential backoff calculation. The delay before the n-th retry (0-indexed) is roughly HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS * (2^n) + jitter.
    • Default Behavior: 300 (milliseconds) (if the environment variable is not set, is empty, or is not a valid integer).

4. Stdio Connection Retry for Tool Calls

For tools/call operations directed to Stdio-based backend servers, the proxy implements a retry mechanism for connection errors (e.g., process crash or unresponsiveness).

Retry Mechanism: If an initial Stdio connection or tool call fails, the proxy will attempt to restart the Stdio process and retry the request. This mechanism follows an exponential backoff strategy similar to HTTP retries.

Configuration: These settings are primarily controlled by environment variables.

  • RETRY_STDIO_TOOL_CALL (environment variable):

    • Set to "true" to enable Stdio tool call retries.
    • Set to "false" to disable this feature.
    • Default Behavior: true (if the environment variable is not set, is empty, or is an invalid value).

  • STDIO_TOOL_CALL_MAX_RETRIES (environment variable):

    • Specifies the maximum number of retry attempts after the initial failed attempt. For example, if set to "2"๏ผŒthere will be one initial attempt and up to two retry attempts, totaling a maximum of three attempts.
    • Default Behavior: 2 (if the environment variable is not set, is empty, or is not a valid integer).

  • STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS (environment variable):

    • The base delay in milliseconds used in the exponential backoff calculation. The delay before the n-th retry (0-indexed) is roughly STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS * (2^n) + jitter.
    • Default Behavior: 300 (milliseconds) (if the environment variable is not set, is empty, or is not a valid integer).

General Notes on Environment Variable Parsing:

  • Boolean environment variables (RETRY_SSE_TOOL_CALL, RETRY_HTTP_TOOL_CALL, RETRY_STDIO_TOOL_CALL) are considered true if their lowercase value is exactly "true". Any other value (including empty or not set) results in the default being applied or false if the default is false (though for these specific variables, the default is true)ใ€‚
  • Numeric environment variables (SSE_TOOL_CALL_MAX_RETRIES, SSE_TOOL_CALL_RETRY_DELAY_BASE_MS, HTTP_TOOL_CALL_MAX_RETRIES, HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS, STDIO_TOOL_CALL_MAX_RETRIES, STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS) are parsed as base-10 integers. If parsing fails (e.g., the value is not a number, or the variable is empty/not set), the default value is usedใ€‚

Development

The MCP Proxy Server includes features to improve its resilience and the reliability of interactions with backend MCP services, ensuring smoother operations and more consistent tool execution.

1. Error Propagation

The proxy server ensures that errors originating from backend MCP services are consistently propagated to the requesting client. These errors are formatted as standard JSON-RPC error responses, making it easier for clients to handle them uniformly.

2. SSE Connection Retry for Tool Calls

When a tools/call operation is made to an SSE-based backend server, and the underlying connection is lost or experiences an error, the proxy server will automatically attempt to:

  1. Re-establish the connection to the SSE backend.
  2. If reconnection is successful, it will retry the original tools/call request once.

This behavior helps mitigate transient network issues that might temporarily disrupt SSE connections.

Configuration: This feature is primarily controlled by the RETRY_SSE_TOOL_CALL_ON_DISCONNECT environment variable.

  • RETRY_SSE_TOOL_CALL_ON_DISCONNECT (environment variable):
    • Set to "true" to enable the automatic reconnect and retry.
    • Set to "false" to disable this feature.
    • Default Behavior: true (if the environment variable is not set, is empty, or is an invalid value).
    • Note: If this setting is also present in config/mcp_server.json under proxy, the environment variable takes precedence.

Example (Environment Variable):

export RETRY_SSE_TOOL_CALL_ON_DISCONNECT="true"

(The JSON example for mcp_server.json under "Proxy Behavior Configuration" illustrates where other proxy settings might go, but this specific setting is best managed via its environment variable.)

3. HTTP Request Retry for Tool Calls

For tools/call operations directed to HTTP-based backend servers, the proxy implements a retry mechanism for connection errors (e.g., "failed to fetch", network timeouts).

Retry Mechanism: If an initial HTTP request fails due to a connection error, the proxy will retry the request using an exponential backoff strategy. This means the delay before each subsequent retry attempt increases exponentially, with a small amount of jitter (randomness) added to prevent thundering herd scenarios.

Configuration: These settings are primarily controlled by environment variables. Values in config/mcp_server.json under the proxy object for these specific keys will be overridden by environment variables if set.

  • RETRY_HTTP_TOOL_CALL (environment variable):

    • Set to "true" to enable retries for HTTP tool calls.
    • Set to "false" to disable this feature.
    • Default Behavior: true (if the environment variable is not set, is empty, or is an invalid value).

  • HTTP_TOOL_CALL_MAX_RETRIES (environment variable):

    • Specifies the maximum number of retry attempts after the initial failed attempt. For example, if set to "2", there will be one initial attempt and up to two retry attempts, totaling a maximum of three attempts.
    • Default Behavior: 2 (if the environment variable is not set, is empty, or is not a valid integer).

  • HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS (environment variable):

    • The base delay in milliseconds used in the exponential backoff calculation. The delay before the n-th retry (0-indexed) is roughly HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS * (2^n) + jitter.
    • Default Behavior: 300 (milliseconds) (if the environment variable is not set, is empty, or is not a valid integer).

General Notes on Environment Variable Parsing:

  • Boolean environment variables (RETRY_SSE_TOOL_CALL, RETRY_HTTP_TOOL_CALL, RETRY_STDIO_TOOL_CALL) are considered true if their lowercase value is exactly "true". Any other value (including empty or not set) results in the default being applied or false if the default is false (though for these specific variables, the default is true).
  • Numeric environment variables (SSE_TOOL_CALL_MAX_RETRIES, SSE_TOOL_CALL_RETRY_DELAY_BASE_MS, HTTP_TOOL_CALL_MAX_RETRIES, HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS, STDIO_TOOL_CALL_MAX_RETRIES, STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS) are parsed as base-10 integers. If parsing fails (e.g., the value is not a number, or the variable is empty/not set), the default value is used.

Example (Environment Variables):

export RETRY_HTTP_TOOL_CALL="true"
export HTTP_TOOL_CALL_MAX_RETRIES="3"
export HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS="500"

4. Stdio Connection Retry for Tool Calls

For tools/call operations directed to Stdio-based backend servers, the proxy implements a retry mechanism for connection errors (e.g., process crash or unresponsiveness).

Retry Mechanism: If an initial Stdio connection or tool call fails, the proxy will attempt to restart the Stdio process and retry the request. This mechanism follows an exponential backoff strategy similar to HTTP retries.

Configuration: These settings are primarily controlled by environment variables.

  • RETRY_STDIO_TOOL_CALL (environment variable):

    • Set to "true" to enable Stdio tool call retries.
    • Set to "false" to disable this feature.
    • Default Behavior: true (if the environment variable is not set, is empty, or is an invalid value).

  • STDIO_TOOL_CALL_MAX_RETRIES (environment variable):

    • Specifies the maximum number of retry attempts after the initial failed attempt. For example, if set to "2", there will be one initial attempt and up to two retry attempts, totaling a maximum of three attempts.
    • Default Behavior: 2 (if the environment variable is not set, is empty, or is not a valid integer).

  • STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS (environment variable):

    • The base delay in milliseconds used in the exponential backoff calculation. The delay before the n-th retry (0-indexed) is roughly STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS * (2^n) + jitter.
    • Default Behavior: 300 (milliseconds) (if the environment variable is not set, is empty, or is not a valid integer).

General Notes on Environment Variable Parsing:

  • Boolean environment variables (RETRY_SSE_TOOL_CALL, RETRY_HTTP_TOOL_CALL, RETRY_STDIO_TOOL_CALL) are considered true if their lowercase value is exactly "true". Any other value (including empty or not set) results in the default being applied or false if the default is false (though for these specific variables, the default is true)ใ€‚
  • Numeric environment variables (SSE_TOOL_CALL_MAX_RETRIES, SSE_TOOL_CALL_RETRY_DELAY_BASE_MS, HTTP_TOOL_CALL_MAX_RETRIES, HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS, STDIO_TOOL_CALL_MAX_RETRIES, STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS) are parsed as base-10 integers. If parsing fails (e.g., the value is not a number, or the variable is empty/not set), the default value is used.

Development

Install dependencies:

npm install
# or yarn install

Build the server (compiles TypeScript to JavaScript in build/):

npm run build

Run in development mode (uses tsx for direct TS execution with auto-restart on changes):

# Run as a Stdio MCP server (default mode)
npm run dev

# Run as an SSE MCP server (enables SSE endpoint and Admin UI if configured)
# Ensure environment variables (PORT, ENABLE_ADMIN_UI etc.) are set as needed
ENABLE_ADMIN_UI=true npm run dev:sse

Watch for changes and rebuild automatically (useful if not using tsx):

npm run watch

Debugging

Use the MCP Inspector for debugging communication (primarily for Stdio mode):

npm run inspector

This script wraps the execution of the built server (build/index.js) with the inspector. Access the inspector UI via the URL provided in the console output. For SSE mode, standard browser developer tools can be used to inspect network requests.

Reference

This project was originally inspired by and refactored from adamwattis/mcp-proxy-server.