Configuration Reference

Complete reference for MCPProxy configuration file (mcp_config.json). This document covers all configuration options, their defaults, and usage examples.

Table of Contents

1. Configuration File Location
2. Basic Configuration
3. Server Configuration
4. Security Settings
5. Tokenizer Configuration
6. TLS/HTTPS Configuration
7. Logging Configuration
8. Docker Isolation
9. Docker Recovery
10. Environment Configuration
11. Code Execution
12. Feature Flags
13. Registries
14. Complete Example

Configuration File Location

MCPProxy looks for configuration in these locations (in order):

Note: At first launch, MCPProxy automatically generates a minimal configuration file if none exists.

Basic Configuration

Network Binding

{
  "listen": "127.0.0.1:8080"
}

Examples:

• "127.0.0.1:8080" - Localhost only (default, secure)
• ":8080" - All network interfaces (use with caution)
• "0.0.0.0:9000" - All interfaces on port 9000

Data Directory

{
  "data_dir": "~/.mcpproxy"
}

Tray Application

{
  "enable_socket": true,
  "tray_endpoint": ""
}

Search & Tool Limits

{
  "tools_limit": 15,
  "tool_response_limit": 20000,
  "call_tool_timeout": "2m"
}

Discovery & Health Checks

mcpproxy keeps each upstream connection alive and its tool index fresh with two background loops. Both intervals are tunable globally and per server, so you can quiet a chatty upstream that returns a large tool catalog.

{
  "health_check_interval": "30s",
  "tool_discovery_interval": "5m"
}

Docker-isolated servers. health_check_interval has no effect on Docker-isolated servers. Their liveness is monitored separately at the container level on a fixed internal cadence (not an MCP ping), so the periodic ping probe is intentionally skipped for them. tool_discovery_interval still applies to Docker servers. Remote (HTTP/SSE) servers benefit most from the ping switch, since both the probe and the former tools/list crossed the network.

Liveness uses ping, not tools/list. The health-check loop issues the MCP-standard ping request rather than re-listing every tool, so an idle proxy no longer generates large recurring tools/list traffic to upstream servers (GitHub #608). Tool changes are still picked up reactively whenever a server pushes notifications/tools/list_changed.

Disabling a loop ("0s"). Set either key to "0s" to turn the corresponding loop off:

• health_check_interval: "0s" — no periodic liveness probe. A dead transport is then detected lazily, on the next real tool call or discovery sweep, rather than proactively.
• tool_discovery_interval: "0s" — no periodic index rebuild. Tools are still discovered at connect time and whenever a server pushes notifications/tools/list_changed. Trade-off: a server that does not support list_changed will not have new/removed tools reflected until it reconnects or you trigger a manual refresh.

An unset key behaves exactly as before this feature (the built-in default), and a change to either interval takes effect on the next cycle without restarting the proxy.

Per-server override. Both keys can also be set on an individual server entry under mcpServers[] (see Server Fields) to override the global value for just that server; the per-server value wins, and "0s" disables the loop for that server only. A dedicated per-server form control in the Web UI / macOS app is planned; for now set per-server overrides via the Raw JSON editor or the REST API.

Debug & Development

{
  "debug_search": false,
  "enable_prompts": true,
  "check_server_repo": true
}

Server Configuration

Basic Server Structure

{
  "mcpServers": [
    {
      "name": "my-server",
      "protocol": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"],
      "working_dir": "/path/to/project",
      "env": {
        "API_KEY": "secret-value"
      },
      "enabled": true,
      "quarantined": false
    }
  ]
}

Server Fields

Protocol Types

stdio - Standard input/output (local processes):

{
  "name": "local-server",
  "protocol": "stdio",
  "command": "python",
  "args": ["-m", "my_mcp_server"],
  "working_dir": "/path/to/project"
}

http - HTTP transport:

{
  "name": "remote-server",
  "protocol": "http",
  "url": "https://api.example.com/mcp",
  "headers": {
    "Authorization": "Bearer token"
  }
}

sse - Server-Sent Events:

{
  "name": "sse-server",
  "protocol": "sse",
  "url": "https://api.example.com/mcp/sse"
}

streamable-http - Streamable HTTP (MCP standard):

{
  "name": "streamable-server",
  "protocol": "streamable-http",
  "url": "https://api.example.com/mcp"
}

auto - Auto-detect from command or url:

{
  "name": "auto-server",
  "protocol": "auto",
  "command": "npx",
  "args": ["-y", "my-server"]
}

Locally-launched HTTP / SSE servers

By default command is only used for stdio servers. When you set command together with an HTTP/SSE url and an explicit protocol of http, sse, or streamable-http, mcpproxy will:

1. Spawn the command (with args, env, working_dir, and Docker isolation exactly like a stdio server).
2. Wait up to launcher_wait_timeout (default 30s) for url to accept a TCP connection.
3. Connect via the configured HTTP/SSE transport.
4. Own the child's lifecycle — the process is stopped (SIGTERM, then SIGKILL after a grace period) on disconnect, restart, server-disable, or mcpproxy shutdown. Unexpected exits trigger an automatic disconnect, which the existing reconnect path picks up.

{
  "name": "local-http-mcp",
  "protocol": "http",
  "url": "http://127.0.0.1:9999/mcp",
  "command": "node",
  "args": ["./examples/echo-http-server.js", "--port", "9999"],
  "working_dir": "/path/to/repo",
  "launcher_wait_timeout": "15s",
  "enabled": true
}

stdout and stderr of the child are routed to the per-server log, so mcpproxy upstream logs <name> continues to work the same way it does for stdio servers.

Behaviour matrix when both command and url are set

The "command wins" rule under auto is intentional: it preserves backwards compatibility with configurations written before the launcher feature existed. To launch a local HTTP/SSE server you must set protocol explicitly to one of http, sse, or streamable-http.

OAuth Configuration

{
  "oauth": {
    "client_id": "your-client-id",
    "client_secret": "secret-reference",
    "redirect_uri": "http://localhost:8080/oauth/callback",
    "scopes": ["repo", "user"],
    "pkce_enabled": true
  }
}

See OAuth Documentation for complete details.

Security Settings

{
  "api_key": "your-secret-api-key",
  "read_only_mode": false,
  "disable_management": false,
  "allow_server_add": true,
  "allow_server_remove": true
}

Security Notes:

• API Key: Set via --api-key flag, MCPPROXY_API_KEY environment variable, or config file
• Empty API Key: Empty values are replaced with an auto-generated key; authentication is always enforced
• Auto-Generation: If no API key is provided, one is generated and logged for easy access
• Tray Integration: Tray app automatically manages API keys for core communication

Tokenizer Configuration

The tokenizer provides local token counting using the tiktoken library. It does not access LLMs or make API calls—it's purely for counting tokens in text locally.

Basic Configuration

{
  "tokenizer": {
    "enabled": true,
    "default_model": "gpt-4",
    "encoding": "cl100k_base"
  }
}

How Tokenizer Works

Important: The tokenizer does not access LLMs. It performs local token counting using the tiktoken algorithm:

1. Local Processing: All token counting happens locally using the tiktoken library
2. No Network Calls: No API requests or external services are used
3. Model Mapping: The default_model field is used to look up the appropriate encoding via GetEncodingForModel()
4. Encoding Selection: If a model isn't recognized, it falls back to the encoding field or cl100k_base

Supported Models & Encodings

The tokenizer automatically maps model names to encodings:

GPT-4o Series (uses o200k_base):

• gpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.5, gpt-4o-2024-05-13, gpt-4o-2024-08-06

GPT-4 & GPT-3.5 Series (uses cl100k_base):

• gpt-4, gpt-4-turbo, gpt-3.5-turbo, gpt-3.5-turbo-16k, text-embedding-ada-002, etc.

Claude Models (uses cl100k_base as approximation):

• claude-3-5-sonnet, claude-3-opus, claude-3-sonnet, claude-3-haiku, claude-2.1, claude-2.0, claude-instant
• Note: Claude models use cl100k_base as an approximation. For accurate counts, use Anthropic's count_tokens API.

Codex Series (uses p50k_base):

• code-davinci-002, code-davinci-001, code-cushman-002, code-cushman-001

Older GPT-3 Series (uses r50k_base):

• text-davinci-003, text-davinci-002, davinci, curie, babbage, ada

Supported Encodings

Usage Examples

For GPT-4:

{
  "tokenizer": {
    "enabled": true,
    "default_model": "gpt-4",
    "encoding": "cl100k_base"
  }
}

For Claude Models:

{
  "tokenizer": {
    "enabled": true,
    "default_model": "claude-3-5-sonnet",
    "encoding": "cl100k_base"
  }
}

For GPT-4o:

{
  "tokenizer": {
    "enabled": true,
    "default_model": "gpt-4o",
    "encoding": "o200k_base"
  }
}

Disable Token Counting:

{
  "tokenizer": {
    "enabled": false
  }
}

What Tokenizer Is Used For

• Token Usage Tracking: Counts tokens in MCP tool calls and responses
• Token Savings Calculation: Calculates token savings from caching
• Metrics & Monitoring: Provides token metrics for observability
• Response Truncation: Helps determine when to truncate large responses

TLS/HTTPS Configuration

{
  "tls": {
    "enabled": false,
    "require_client_cert": false,
    "certs_dir": "",
    "hsts": true
  }
}

Quick Setup:

1. Trust certificate: mcpproxy trust-cert
2. Enable TLS: Set "enabled": true or MCPPROXY_TLS_ENABLED=true
3. Update client URLs to use https://

See Setup Guide - HTTPS for complete details.

Logging Configuration

{
  "logging": {
    "level": "info",
    "enable_file": false,
    "enable_console": true,
    "filename": "main.log",
    "log_dir": "",
    "max_size": 10,
    "max_backups": 5,
    "max_age": 30,
    "compress": true,
    "json_format": false
  }
}

Log Locations (defaults):

• macOS: ~/Library/Logs/mcpproxy/main.log
• Linux: ~/.local/state/mcpproxy/logs/main.log (or /var/log/mcpproxy when running as root)
• Windows: %LOCALAPPDATA%\mcpproxy\logs\main.log
• Per-server logs: same directory, server-{name}.log (characters in the server name that aren't letters, digits, ., -, or _ — such as the / in registry names like io.github.evidai/polymarket-guard — are sanitized to _, so the log is always a single flat file)
• Custom: set log_dir to override (supports ~ expansion)

Behavior notes:

• mcpproxy serve enables file logging by default unless --log-to-file is explicitly set to false

See Logging Documentation for complete details.

Docker Isolation

Global Docker Isolation Settings

{
  "docker_isolation": {
    "enabled": false,
    "default_images": {
      "python": "python:3.11",
      "node": "node:20",
      "npx": "node:20"
    },
    "registry": "docker.io",
    "network_mode": "bridge",
    "memory_limit": "512m",
    "cpu_limit": "1.0",
    "timeout": "30s",
    "extra_args": [],
    "log_driver": "",
    "log_max_size": "100m",
    "log_max_files": "3"
  }
}

Default Docker Images

{
  "python": "python:3.11",
  "python3": "python:3.11",
  "uvx": "python:3.11",
  "pip": "python:3.11",
  "pipx": "python:3.11",
  "node": "node:20",
  "npm": "node:20",
  "npx": "node:20",
  "yarn": "node:20",
  "go": "golang:1.21-alpine",
  "cargo": "rust:1.75-slim",
  "rustc": "rust:1.75-slim",
  "binary": "alpine:3.18",
  "sh": "alpine:3.18",
  "bash": "alpine:3.18",
  "ruby": "ruby:3.2-alpine",
  "gem": "ruby:3.2-alpine",
  "php": "php:8.2-cli-alpine",
  "composer": "php:8.2-cli-alpine"
}

Per-Server Isolation Settings

{
  "mcpServers": [
    {
      "name": "isolated-server",
      "isolation": {
        "enabled": true,
        "image": "custom-image:latest",
        "network_mode": "none",
        "extra_args": ["--cap-drop=ALL"],
        "working_dir": "/app",
        "log_driver": "json-file",
        "log_max_size": "50m",
        "log_max_files": "2"
      }
    }
  ]
}

See Docker Isolation Documentation for complete details.

Docker Recovery

{
  "docker_recovery": {
    "enabled": true,
    "check_intervals": ["2s", "5s", "10s", "30s", "60s"],
    "max_retries": 0,
    "notify_on_start": true,
    "notify_on_success": true,
    "notify_on_failure": true,
    "notify_on_retry": false,
    "persistent_state": true
  }
}

See Docker Recovery Documentation for complete details.

Environment Configuration

{
  "environment": {
    "inherit_system_safe": true,
    "allowed_system_vars": [
      "PATH",
      "HOME",
      "TMPDIR",
      "NODE_PATH"
    ],
    "custom_vars": {
      "CUSTOM_VAR": "value"
    },
    "enhance_path": false
  }
}

Default Allowed System Variables:

• Core: PATH, HOME, TMPDIR, TEMP, TMP, SHELL, TERM, LANG, USER, USERNAME
• Windows-specific: USERPROFILE, APPDATA, LOCALAPPDATA, PROGRAMFILES, SYSTEMROOT, COMSPEC
• Unix/XDG: XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_CACHE_HOME, XDG_RUNTIME_DIR
• Locale: all LC_* variables (e.g., LC_ALL, LC_CTYPE, …)
• Custom additions: custom_vars merged on top

Routing Mode

Controls how upstream MCP tools are exposed to AI agents on the default /mcp endpoint.

{
  "routing_mode": "retrieve_tools"
}

Available modes:

All three modes are always available on dedicated endpoints regardless of config: /mcp/all (direct), /mcp/code (code_execution), /mcp/call (retrieve_tools).

See Routing Modes for complete details.

Server Instructions

Text returned in the MCP initialize response to guide AI agents on how to use the proxy (e.g., use retrieve_tools to discover existing tools rather than search_servers).

{
  "instructions": "Use retrieve_tools to discover tools before assuming a capability is unavailable."
}

You can edit this from the Web UI under Settings → Advanced → MCP server instructions. The textarea shows the built-in default as a greyed-out placeholder; clearing it restores that default.

Note: Applied at startup / on the next client connect — editing this value does not hot-reload into already-connected MCP sessions.

Tool-Level Quarantine

SHA256 hash-based tool approval system that detects changes to tool descriptions and schemas.

{
  "quarantine_enabled": true
}

Per-server quarantine skip is configured on the server entry:

{
  "mcpServers": [
    {
      "name": "trusted-server",
      "command": "my-server",
      "skip_quarantine": true
    }
  ]
}

See Tool Quarantine for complete details.

Code Execution

{
  "enable_code_execution": false,
  "code_execution_timeout_ms": 120000,
  "code_execution_max_tool_calls": 0,
  "code_execution_pool_size": 10
}

Code execution supports both JavaScript (ES2020+) and TypeScript. TypeScript code is automatically transpiled via esbuild before execution.

See Code Execution Documentation for complete details.

Feature Flags

{
  "features": {
    "enable_runtime": true,
    "enable_event_bus": true,
    "enable_sse": true,
    "enable_observability": true,
    "enable_health_checks": true,
    "enable_metrics": true,
    "enable_tracing": false,
    "enable_oauth": true,
    "enable_quarantine": true,
    "enable_docker_isolation": false,
    "enable_search": true,
    "enable_caching": true,
    "enable_async_storage": true,
    "enable_web_ui": true,
    "enable_debug_logging": false,
    "enable_contract_tests": false
  }
}

Note: Feature flags are typically managed internally. Most users don't need to modify these settings.

Registries

The three default registries ship built-in and require no configuration. Use the registries array only to add your own custom source:

{
  "registries": [
    {
      "id": "mycorp",
      "name": "My Corp Registry",
      "description": "Internal MCP server catalog",
      "url": "https://registry.mycorp.example/",
      "servers_url": "https://registry.mycorp.example/v0.1/servers",
      "tags": ["internal"],
      "protocol": "modelcontextprotocol/registry"
    }
  ]
}

Default Registries (shipped built-in, no configuration required):

• official — Official MCP Registry (modelcontextprotocol/registry): primary, zero-config aggregator
• reference — Reference Servers (builtin/reference): curated @modelcontextprotocol servers, shipped in-binary so the basics work offline
• docker-mcp-catalog — Docker MCP Catalog (custom/docker): signed-container MCP server inventory

Deprecated former-defaults: earlier versions also shipped pulse, smithery, fleur, azure-mcp-demo, and remote-mcp-servers as defaults. These were removed and are pruned from an existing mcp_config.json on load, so upgrades converge to the three defaults above. Genuinely user-added custom registries are never touched; pulse/smithery can be added back as custom sources.

See Registries Documentation and Search Servers Documentation for complete details.

Observability

Controls the usage-statistics aggregate that powers the Web UI usage graphs (spec 069). The aggregate is built incrementally from the activity log, kept in memory as an immutable snapshot, and periodically persisted so it survives restarts without a full re-scan.

{
  "observability": {
    "usage_cache_ttl": "5s",
    "usage_persist_interval": "30s"
  }
}

Both fields are optional, accept Go duration strings (e.g. "10s", "1m"), and are hot-reloadable. Non-positive values fall back to the defaults.

Complete Example

Here's a complete configuration example with all major sections:

Note: Leaving api_key empty will cause MCPProxy to generate and enforce a new key on startup.

{
  "listen": "127.0.0.1:8080",
  "data_dir": "~/.mcpproxy",
  "enable_socket": true,
  "api_key": "",
  "tools_limit": 15,
  "tool_response_limit": 20000,
  "call_tool_timeout": "2m",
  "debug_search": false,
  "enable_prompts": true,
  "check_server_repo": true,

  "tokenizer": {
    "enabled": true,
    "default_model": "gpt-4",
    "encoding": "cl100k_base"
  },

  "tls": {
    "enabled": false,
    "require_client_cert": false,
    "hsts": true
  },

  "logging": {
    "level": "info",
    "enable_file": false,
    "enable_console": true,
    "filename": "main.log",
    "max_size": 10,
    "max_backups": 5,
    "max_age": 30,
    "compress": true,
    "json_format": false
  },

  "mcpServers": [
    {
      "name": "everything",
      "protocol": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"],
      "enabled": true,
      "quarantined": false
    },
    {
      "name": "github",
      "protocol": "http",
      "url": "https://api.github.com/mcp",
      "oauth": {
        "scopes": ["repo", "user"],
        "pkce_enabled": true
      },
      "enabled": true
    }
  ],

  "docker_isolation": {
    "enabled": false
  },

  "docker_recovery": {
    "enabled": true,
    "notify_on_start": true,
    "notify_on_success": true,
    "notify_on_failure": true
  },

  "environment": {
    "inherit_system_safe": true,
    "allowed_system_vars": ["PATH", "HOME", "TMPDIR"],
    "custom_vars": {},
    "enhance_path": false
  },

  "enable_code_execution": false,
  "code_execution_timeout_ms": 120000,
  "code_execution_max_tool_calls": 0,
  "code_execution_pool_size": 10,

  "read_only_mode": false,
  "disable_management": false,
  "allow_server_add": true,
  "allow_server_remove": true
}

Environment Variables

Many configuration options can be overridden via environment variables:

Prefix rules:

• General settings also accept the MCPP_ prefix (hyphens become underscores), e.g., MCPP_TOOLS_LIMIT, MCPP_ENABLE_PROMPTS.
• TLS/listen/data have additional convenience overrides with the MCPPROXY_ prefix as listed above.

Priority: Environment variables > Config file > Defaults

Validation

MCPProxy validates configuration on startup. Common validation errors:

• Invalid listen address: Must be host:port or :port format
• Invalid tools_limit: Must be between 1 and 1000
• Missing server name: Each server must have a unique name
• Invalid protocol: Must be stdio, http, sse, streamable-http, or auto
• Missing command: stdio servers require command field
• Missing url: HTTP-based servers require url field
• Invalid timeout: Must be a valid duration string (e.g., "30s", "2m")

Run mcpproxy doctor to check configuration health.

Related Documentation

• Setup Guide - Initial setup and client configuration
• OAuth Documentation - OAuth authentication setup
• Docker Isolation - Docker security isolation
• Logging - Logging configuration and management
• Code Execution - JavaScript code execution
• Search Servers - MCP server discovery