MCP Proxy Server

The MCP Proxy Server acts as a central hub for Model Context Protocol (MCP) resources. It can connect to and manage multiple backend MCP servers of various types (Stdio, SSE, and Streamable HTTP) and aggregate their tools and resources into a unified interface.

It serves two primary roles:

1. Proxy Mode: Aggregates capabilities from multiple backends and exposes them via unified SSE (/sse) or Streamable HTTP (/mcp) endpoints.
2. Server Mode: Operates as a standalone MCP server, including support for pure Stdio mode.

Key capabilities include request routing to correct backends, response aggregation, support for concurrent SSE client connections, and optional API authentication.

The MCP Proxy Server acts as a central hub for Model Context Protocol (MCP) resource servers. It aggregates multiple backend MCP servers (supporting Stdio, SSE, and Streamable HTTP types) and exposes their combined tools and resources through a single, unified interface.

It can operate in three primary modes:

1. Proxy Mode: Connects to multiple backend servers and exposes them via SSE (/sse) or Streamable HTTP (/mcp) endpoints.
2. Stdio Mode: Acts as a single Stdio-based MCP server.
3. Aggregator: Routes tool calls and resource requests to the appropriate backend server while maintaining consistent URI schemes.

When running in proxy mode, the server performs the following tasks:

• Discovery: Connects to multiple MCP resource servers defined in config/mcp_server.json.
• Aggregation: Combines tools and resources from all currently active connected servers.
• Routing: Routes tool calls and resource access requests to the appropriate backend server.
• URI Management: Maintains a consistent URI scheme across all aggregated resources.

Error Propagation

Errors originating from backend MCP services are formatted as standard JSON-RPC error responses and propagated to the requesting client to ensure uniform error handling.

Retry Mechanism Details

• Exponential Backoff: The delay before the n-th retry (0-indexed) is calculated as: BASE_DELAY_MS * (2^n) + jitter.
• Parsing Rules:
  • Booleans: Variables like RETRY_SSE_TOOL_CALL are true only if the lowercase value is exactly "true". Otherwise, the default is applied.
  • Numbers: Variables like MAX_RETRIES and RETRY_DELAY_BASE_MS are parsed as base-10 integers. If parsing fails or the variable is empty, the default value is used.

The core configuration files for the MCP Proxy Server are stored in a persistent directory mapped from the container's /mcp-proxy-server/config to your Home Assistant host (typically under /config/addons_config/mcp_proxy_server/).

To define backend servers or tool overrides, place the following files in that directory:

• mcp_server.json: Defines backend MCP servers.
• tool_config.json: Defines tool overrides (enabling/disabling tools or changing names/descriptions).

If these files are missing when the add-on starts, example versions may be copied into the directory for you to edit.

When using stdio type servers, you can automate installation via the Admin UI using installDirectory and installCommands in mcp_server.json.

Installation Directory Logic

1. If installDirectory is provided in mcp_server.json, use that absolute path.
2. If omitted, use ${TOOLS_FOLDER}/<server_key>.
3. If TOOLS_FOLDER is not set, use ./tools/<server_key>.

Installation Commands

• installCommands: An array of shell commands executed sequentially if the target directory does not exist.
• Warning: Commands are executed from the parent directory of the target installation directory. Use with extreme caution.

Environment Variables

• TOOLS_FOLDER: Base directory for Stdio server installations (e.g., /srv/mcp_tools).

When ENABLE_ADMIN_UI is enabled, the web interface provides several management capabilities:

• Server Configuration: View, add, edit, and delete server entries in config/mcp_server.json. Supported types include Stdio, SSE, and HTTP. Configuration options include type, command, args, env, url, apiKey, bearerToken, and install config.
• Tool Configuration: View all tools discovered from active backend servers. You can enable or disable specific tools and override their display names and descriptions in config/tool_config.json.
• Live Reload: Apply changes to server or tool configurations without restarting the proxy server process.
• Stdio Installation Monitoring: For Stdio-based servers, you can trigger installation commands and monitor stdout and stderr in real-time directly within the UI.

To use the proxy with an MCP client (like Claude Desktop), configure the client to connect to the add-on's SSE endpoint:

• URL: http://<your-home-assistant-ip>:<port_configured_in_options>/sse
• Authentication: If you configured mcp_proxy_sse_allowed_keys, the client must provide one of the keys. This is typically done via:
  • An X-Api-Key header
  • A ?key=<your_key> query parameter in the URL.

You can run the proxy server in a mode that starts an HTTP server (e.g., using npm run dev:sse or a Docker container). Clients can then connect to the proxy via network endpoints.

Endpoints:

• SSE: http://localhost:3663/sse
• Streamable HTTP: http://localhost:3663/mcp

If authentication is enabled via ALLOWED_KEYS or ALLOWED_TOKENS, you must provide credentials using one of the following methods:

Authentication Methods

• API Key:
  • For /sse: Use the URL query parameter ?key=....
  • For both /sse and /mcp: Use the X-Api-Key header.
• Bearer Token: Use the Authorization: Bearer <token> header.

// Example for Claude Desktop connecting to SSE with an API Key
{
  "mcpServers": {
    "my-proxy-sse": {
      "type": "sse",
      "name": "MCP Proxy (SSE)",
      "url": "http://localhost:3663/sse?key=clientkey1"
    }
  }
}

The MCP Proxy Server includes an optional Web Admin UI for managing server configurations and tools through a browser-based interface. To enable this feature, set the following environment variable:

ENABLE_ADMIN_UI=true

Warning: The Admin UI includes a web-based terminal that provides shell access to the server's environment. Use this feature with extreme caution, especially if the management interface is exposed to external networks.