Configuration File

MCPProxy uses a JSON configuration file located at ~/.mcpproxy/mcp_config.json.

Location

Complete Reference

{
  "listen": "127.0.0.1:8080",
  "data_dir": "~/.mcpproxy",
  "api_key": "your-secret-api-key",
  "enable_socket": true,
  "health_check_interval": "30s",
  "tool_discovery_interval": "5m",
  "tools_limit": 15,
  "tool_response_limit": 20000,
  "enable_code_execution": false,
  "code_execution_timeout_ms": 120000,
  "code_execution_max_tool_calls": 0,
  "code_execution_pool_size": 10,
  "features": {
    "enable_web_ui": true
  },
  "update_check": {
    "enabled": true,
    "channel": "stable"
  },
  "mcpServers": []
}

Options

Server Settings

Feature Flags

Tool Discovery Settings

Tool Discovery & Health Check Intervals

MCPProxy keeps upstream connections fresh with two independent background loops:

• a lightweight liveness probe that sends a standard MCP ping to confirm the connection is alive, and
• a periodic tool-discovery sweep that re-lists tools to rebuild the search index. (Tool changes are also picked up reactively via notifications/tools/list_changed; the sweep is a fallback for servers that don't advertise listChanged.)

Both cadences are configurable globally, and can be overridden per server (see Upstream Servers). Values are duration strings such as 30s, 5m, or 1h.

Resolution order: per-server value → global value → built-in default. Leaving a key unset preserves the previous behaviour, so existing configs are unaffected by an upgrade.

{
  "health_check_interval": "30s",
  "tool_discovery_interval": "5m",
  "mcpServers": [
    {
      "name": "chatty-server",
      "health_check_interval": "2m",
      "tool_discovery_interval": "0s"
    }
  ]
}

Notes:

• 0s = disabled. Disabling the discovery sweep for a server that does not support listChanged means tool changes are only picked up on (re)connect — fine for static servers, worth knowing for dynamic ones. With the liveness probe disabled, a dead transport is detected lazily (on the next real tool call or discovery sweep) rather than proactively.
• Docker-isolated servers: health_check_interval is a no-op — their liveness is monitored at the container level, not via MCP ping. tool_discovery_interval still applies. Remote (HTTP/SSE) servers benefit most from the ping-based probe.
• Hot reload: interval changes take effect on the next cycle without a full restart.
• These intervals are also editable in the Web UI and macOS app under Settings → Advanced → Tool discovery & health checks.

Code Execution Settings

Update Check Settings

Controls the background upgrade-awareness checker. Both keys are optional and hot-reloadable (no restart needed).

The existing environment switches keep working and win over these keys: MCPPROXY_DISABLE_AUTO_UPDATE=true force-disables checking, and MCPPROXY_ALLOW_PRERELEASE_UPDATES=true force-selects the prerelease channel. They only widen in one direction — they cannot re-enable checking that the config disabled. See Version Updates for where updates are surfaced.

Concurrency Limits & Request Queueing

Caps how many upstream tool calls may run at once, so a burst cannot overwhelm a fragile upstream. Off by default — with no keys set there is no limiting, no queueing and no new errors.

Three separately named scopes carry the same three settings:

{
  "max_concurrent_requests": 50,
  "queue_size": 100,
  "queue_timeout": "30s",

  "server_concurrency_defaults": {
    "max_concurrent_requests": 5,
    "queue_size": 10
  },

  "mcpServers": [
    { "name": "fragile-db", "command": "db-mcp", "max_concurrent_requests": 1, "queue_size": 2 },
    { "name": "fast-api", "url": "https://api.example.com/mcp", "max_concurrent_requests": 0 }
  ]
}

Tri-state per-server semantics. Each per-server key is independent: absent inherits from server_concurrency_defaults, 0 disables that setting for this server (max_concurrent_requests: 0 opts the server out of per-server limiting entirely), and a positive value overrides the default.

The global limiter is never an inheritance source — it applies on top, so a server's effective concurrency is min(per-server limit, global limit). queue_timeout is one total wait budget across both tiers, not one per tier, and queue waiting never eats into the call's execution timeout.

Shedding. A shed call gets a readable, retry-friendly error: an error tool result for MCP calls, HTTP 429 with Retry-After for the REST tool-call endpoint, and an activity record with the rejected status carrying the reason (queue_full or queue_timeout) and scope (server or global). All limits are hot-reloadable.

For stdio upstreams, start at 5 rather than 1: the transport multiplexes and most SDK servers use a small worker pool.

Full reference — validation rules, metrics, and which origins are limited — lives in docs/configuration.md in the repository.

MCP Servers

See Upstream Servers for detailed server configuration.

Hot Reload

MCPProxy watches the configuration file for changes and automatically reloads when modifications are detected. No restart is required for most configuration changes.

Environment Variable Overrides

Configuration options can be overridden using environment variables. See Environment Variables for details.