← Back to Home

Configuration Guide

mcpproxy is configured using a JSON file named mcp_config.json. This file is the single source of truth for the proxy's settings and upstream servers.

Configuration File Location

By default, mcpproxy looks for mcp_config.json inside its data directory, which is typically ~/.mcpproxy/mcp_config.json.

When you first run mcpproxy, it will automatically create a default configuration file if one doesn't exist.

Example Configuration

Here is an example of a complete mcp_config.json file:

{
  "listen": ":8080",
  "data_dir": "/Users/user/.mcpproxy",
  "enable_tray": true,
  "debug_search": false,
  "mcpServers": [
    {
      "name": "coingecko",
      "protocol": "stdio",
      "command": "uvx",
      "args": [
        "git+https://github.com/smart-mcp-proxy/coingecko-mcp-server"
      ],
      "enabled": true,
      "quarantined": false,
      "created": "2025-06-24T21:21:02.665468+03:00",
      "updated": "2025-06-25T18:56:15.163114+03:00"
    },
    {
      "name": "defillama-mcp-server",
      "protocol": "stdio",
      "command": "uvx",
      "args": [
        "git+https://github.com/smart-mcp-proxy/defillama-mcp-server"
      ],
      "enabled": true,
      "quarantined": false,
      "created": "2025-06-24T21:40:25.983266+03:00",
      "updated": "2025-06-25T18:56:16.69157+03:00"
    },
    {
      "name": "context7",
      "url": "https://mcp.context7.com/mcp",
      "protocol": "http",
      "enabled": true,
      "quarantined": false,
      "created": "2025-06-25T18:55:21.393281+03:00",
      "updated": "2025-06-25T18:56:59.510613+03:00"
    },
    {
      "name": "malicious-demo-mcp-server",
      "protocol": "stdio",
      "command": "uvx",
      "args": [
        "git+https://github.com/smart-mcp-proxy/malicious-demo-mcp-server"
      ],
      "enabled": true,
      "quarantined": true,
      "created": "2025-06-25T08:38:43.601706+03:00",
      "updated": "2025-06-25T18:56:17.60542+03:00"
    }
  ],
  "top_k": 5,
  "tools_limit": 15,
  "tool_response_limit": 20000,
  "logging": {
    "level": "info",
    "enable_file": true,
    "enable_console": true,
    "filename": "mcpproxy.log",
    "max_size": 10,
    "max_backups": 5,
    "max_age": 30,
    "compress": true,
    "json_format": false
  },
  "read_only_mode": false,
  "disable_management": false,
  "allow_server_add": true,
  "allow_server_remove": true,
  "enable_prompts": true
}

Managing Upstream Servers with Natural Language

You can manage your upstream MCP servers by simply talking to your LLM assistant. The proxy understands natural language commands to add, update, and remove servers. This is the easiest way to manage your configuration.

You can also manually edit the mcp_config.json file, but using tool calls is recommended for most users.

Adding a Server

To add a server, just ask your LLM. The proxy will understand your intent, add the server to its runtime configuration, and automatically save it to your mcp_config.json file.

Example: Adding an HTTP server

"Add an HTTP server named 'my-api' at the URL http://localhost:3001 and set an Authorization header with 'Bearer my-secret-token'."

Example: Adding a Stdio server

"Add a new stdio server to mcpproxy. Name it 'my-script' and have it run the command 'python -m my_mcp_script'."

Any newly added server is automatically placed in quarantine for security review.

Updating a Server

You can update a server's configuration with a natural language command. This is useful for changing a URL, updating auth headers, or enabling/disabling a server.

Example: Disabling a server

"Disable the 'my-api' server."

Example: Updating a server's details

"Update the 'my-api' server and change its authorization token to 'Bearer new-secret-token'."

Deleting a Server

To remove a server, just ask your LLM.

Example:

"Remove the 'my-api' server from my configuration."

Quarantine Configuration

The quarantined flag on a server object determines its security status.

• "quarantined": true: The server is in quarantine. Its tools can be discovered and inspected for security analysis, but they cannot be executed.
• "quarantined": false: The server is trusted and its tools are fully executable.

For security reasons, a server can only be unquarantined (by setting this flag to false) by either editing the mcp_config.json file directly or by using the System Tray UI. It cannot be done via an LLM tool call.

Read more about the Security Quarantine System.