MCP Settings Configuration

This guide explains how to configure MCP servers in MCPHub using the mcp_settings.json file and related configurations.

Configuration Files Overview

MCPHub uses several configuration files:

mcp_settings.json: Your personal configuration of active MCP servers and system config
servers.json: Metadata cataloging hundreds of available MCP servers
.env: Environment variables and secrets

Basic MCP Settings Structure

mcp_settings.json

{
  "mcpServers": {
    "server-name": {
      "command": "command-to-run",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}

Example Configuration

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"],
      "env": {
        "USER_AGENT": "MCPHub/1.0"
      }
    },
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless"]
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
        "SLACK_TEAM_ID": "${SLACK_TEAM_ID}"
      }
    }
  }
}

Server Configuration Options

A server entry has the shape "<server-name>": ServerConfig. The relevant fields depend on the transport, which is selected by type.

Top-level fields

Field	Type	Required	Description
`type`	`"stdio" \| "sse" \| "streamable-http" \| "openapi"`	Recommended	Transport. Defaults to `stdio` when omitted but a `command` is provided.
`enabled`	boolean	no	Defaults to `true`. Disabled servers stay in settings but are not connected.
`owner`	string	no	Username that owns the entry. Defaults to the creating user or `admin`. Used for user-scoped routes (`/:user/mcp/...`).
`description`	string	no	Free-form description displayed in the dashboard.
`options`	object	no	Per-server runtime options (see `src/types/index.ts`).
`proxy`	object	no	Optional HTTP proxy settings (`url`, `noProxy`, etc.).
`oauth`	object	no	Upstream OAuth client settings (used when the upstream server requires OAuth).
`enableKeepAlive`	boolean	no	For `sse` / `streamable-http`: enable periodic health checks and automatic reconnect attempts.
`keepAliveInterval`	number	no	Health check and reconnect interval in milliseconds. Defaults to `60000`.
`perSessionClient`	boolean	no	Create a dedicated upstream client per downstream MCP session instead of sharing one connection across all sessions. Use for stateful servers like Playwright. See Per-session client isolation.
`tools`, `prompts`, `resources`	object	no	Per-item overrides: `{ "<name>": { "enabled": true, "description": "..." } }`. Managed via the dashboard or the per-resource API endpoints.

`type: "stdio"` (default)

Field	Type	Required	Description
`command`	string	yes	Executable to spawn.
`args`	string[]	no	Command-line arguments.
`env`	object	no	Extra environment variables for the child process. `${ENV}` placeholders in values are expanded against the MCPHub process environment.

`type: "sse"` or `type: "streamable-http"`

Field	Type	Required	Description
`url`	string	yes	Upstream endpoint URL.
`headers`	object	no	Static headers sent on every request.
`passthroughHeaders`	string[]	no	Inbound HTTP header names to forward from the caller to the upstream server.

`type: "openapi"`

Field	Type	Required	Description
`openapi.url`	string	one of `url`/`schema`	URL of an OpenAPI document MCPHub will download.
`openapi.schema`	object	one of `url`/`schema`	Inline OpenAPI document.
`headers`	object	no	Static headers applied to outbound calls.
`passthroughHeaders`	string[]	no	Headers to forward from the caller.

The authoritative definition of every field is the ServerConfig type in src/types/index.ts — consult it if you need behavior not described here.

Common MCP Server Examples

Web and API Servers

Fetch Server

{
  "fetch": {
    "command": "uvx",
    "args": ["mcp-server-fetch"],
    "env": {
      "USER_AGENT": "MCPHub/1.0",
      "MAX_REDIRECTS": "10"
    }
  }
}

Web Scraping with Playwright

{
  "playwright": {
    "command": "npx",
    "args": ["@playwright/mcp@latest", "--headless"],
    "timeout": 60000,
    "env": {
      "PLAYWRIGHT_BROWSERS_PATH": "/tmp/browsers"
    }
  }
}

Per-session client isolation (stateful servers)

By default MCPHub keeps a single upstream connection per server and shares it across every downstream MCP session. For stateful servers this means all clients share the same state — with Playwright, for example, every session drives the same browser instance and its tabs. Set perSessionClient: true to make MCPHub open a dedicated upstream client per downstream session instead. Each session gets its own connection (and, for stdio servers, its own child process), created lazily on first tool call and torn down automatically when the session ends.

perSessionClient is a MCPHub-side setting: it controls how many upstream connections MCPHub opens. It is distinct from Playwright MCP’s own --isolated flag, which controls browser-profile isolation on the Playwright side. The two pair naturally — enable both for fully isolated browser sessions.

{
  "mcpServers": {
    "playwright": {
      "type": "streamable-http",
      "url": "http://playwright-mcp:3000/mcp",
      "perSessionClient": true
    }
  }
}

Or with a locally spawned Playwright MCP using its --isolated flag:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless", "--isolated"],
      "perSessionClient": true
    }
  }
}

Only enable perSessionClient for servers that actually hold per-session state. It multiplies upstream connections (and stdio child processes) by the number of concurrent sessions, so leave it off for stateless servers.

File and System Servers

Filesystem Server

{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
    "env": {
      "ALLOWED_OPERATIONS": "read,write,list"
    }
  }
}

SQLite Server

{
  "sqlite": {
    "command": "uvx",
    "args": ["mcp-server-sqlite", "--db-path", "/path/to/database.db"],
    "env": {
      "SQLITE_READONLY": "false"
    }
  }
}

Communication Servers

Slack Server

{
  "slack": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-slack"],
    "env": {
      "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
      "SLACK_TEAM_ID": "${SLACK_TEAM_ID}",
      "SLACK_APP_TOKEN": "${SLACK_APP_TOKEN}"
    }
  }
}

Development and API Servers

GitHub Server

{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
    }
  }
}

Map and Location Services

Amap (高德地图) Server

{
  "amap": {
    "command": "npx",
    "args": ["-y", "@amap/amap-maps-mcp-server"],
    "env": {
      "AMAP_MAPS_API_KEY": "${AMAP_API_KEY}"
    }
  }
}

Looking for more servers? The bundled Market catalog in the dashboard lists hundreds of known MCP servers with copy-paste-ready configurations.

Advanced Configuration

Environment Variable Substitution

MCPHub supports environment variable substitution using ${VAR_NAME} syntax:

{
  "mcpServers": {
    "api-server": {
      "command": "python",
      "args": ["-m", "api_server"],
      "env": {
        "API_KEY": "${API_KEY}",
        "API_URL": "${API_BASE_URL}/v1"
      }
    }
  }
}

Proxy Configuration (proxychains4)

MCPHub supports routing STDIO server network traffic through a proxy using proxychains4. This feature is available on Linux and macOS only (Windows is not supported).

To use this feature, you must have proxychains4 installed on your system:

Debian/Ubuntu: apt install proxychains4
macOS: brew install proxychains-ng
Arch Linux: pacman -S proxychains-ng

Basic Proxy Configuration

{
  "mcpServers": {
    "fetch-via-proxy": {
      "command": "uvx",
      "args": ["mcp-server-fetch"],
      "proxy": {
        "enabled": true,
        "type": "socks5",
        "host": "127.0.0.1",
        "port": 1080
      }
    }
  }
}

Proxy Configuration Options

Field	Type	Default	Description
`enabled`	boolean	`false`	Enable/disable proxy routing
`type`	string	`socks5`	Proxy protocol: `socks4`, `socks5`, or `http`
`host`	string	-	Proxy server hostname or IP address
`port`	number	-	Proxy server port
`username`	string	-	Proxy authentication username (optional)
`password`	string	-	Proxy authentication password (optional)
`configPath`	string	-	Path to custom proxychains4 config file

Proxy with Authentication

{
  "mcpServers": {
    "secure-server": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"],
      "proxy": {
        "enabled": true,
        "type": "http",
        "host": "proxy.example.com",
        "port": 8080,
        "username": "${PROXY_USER}",
        "password": "${PROXY_PASSWORD}"
      }
    }
  }
}

Using Custom proxychains4 Configuration

For advanced use cases, you can provide your own proxychains4 configuration file:

{
  "mcpServers": {
    "custom-proxy-server": {
      "command": "python",
      "args": ["-m", "custom_mcp_server"],
      "proxy": {
        "enabled": true,
        "configPath": "/etc/proxychains4/custom.conf"
      }
    }
  }
}

When configPath is specified, all other proxy settings (type, host, port, etc.) are ignored, and the custom configuration file is used directly.

Group Management

Group Configuration

{
  "groups": {
    "production": {
      "name": "Production Tools",
      "description": "Stable production servers",
      "servers": ["fetch", "slack", "github"]
    },
    "experimental": {
      "name": "Experimental Features",
      "description": "Beta and experimental servers",
      "servers": ["experimental-ai", "beta-search"]
    }
  }
}

System Routing Settings

You can also configure runtime routing and authentication behavior under systemConfig.routing in mcp_settings.json:

{
  "systemConfig": {
    "routing": {
      "enableBearerAuth": true,
      "bearerAuthHeaderName": "X-MCP-Authorization",
      "jsonBodyLimit": "5mb",
      "skipAuth": false
    }
  }
}

bearerAuthHeaderName defaults to Authorization and controls which incoming header MCPHub reads for Bearer authentication.
Use a custom header such as X-MCP-Authorization when an upstream MCP/OpenAPI server also needs to passthrough Authorization.
jsonBodyLimit defaults to 1mb and controls the Express JSON parser limit for API requests, including large inline OpenAPI schema uploads.

Tool Result Compression

MCPHub can transparently compress large text tool results before returning them to MCP clients. This is useful when upstream tools return large logs, diffs, search output, JSON arrays, or long text blobs that would otherwise consume too much model context. Tool result compression is disabled by default. Enable and tune it from Settings → Tool Result Compression, or configure it under systemConfig.toolResultCompression:

{
  "systemConfig": {
    "toolResultCompression": {
      "enabled": false,
      "minTokens": 2000,
      "maxOutputTokens": 1200,
      "strategy": "auto"
    }
  }
}

Field	Type	Default	Description
`enabled`	boolean	`false`	Enable transparent compression for successful tool results.
`minTokens`	number	`2000`	Only compress a text block when its estimated token count is at or above this threshold.
`maxOutputTokens`	number	`1200`	Target token budget for each compressed text block.
`strategy`	`"auto" \| "json" \| "log" \| "search" \| "diff" \| "text"`	`"auto"`	Compression strategy. `auto` detects common structured output formats.

Compression only applies to successful tool responses. Responses with isError: true are returned unchanged, non-text content blocks are preserved, and each text block is evaluated independently. When MCPHub compresses a result, it prepends a marker such as:

[mcphub:compressed-tool-result strategy=log original_tokens=9000 compressed_tokens=1200 omitted_lines=240]

The activity log records the original upstream output before compression, so operators can inspect full results in MCPHub even when clients receive compressed content.

Best Practices

Security

Use environment variables for sensitive data:

{
  "env": {
    "API_KEY": "${API_KEY}",
    "DATABASE_PASSWORD": "${DB_PASSWORD}"
  }
}

This comprehensive guide covers all aspects of configuring MCP servers in MCPHub for various use cases and environments.

​MCP Settings Configuration

​Configuration Files Overview

​Basic MCP Settings Structure

​mcp_settings.json

​Example Configuration

​Server Configuration Options

​Top-level fields

​type: "stdio" (default)

​type: "sse" or type: "streamable-http"

​type: "openapi"

​Common MCP Server Examples

​Web and API Servers

​Fetch Server

​Web Scraping with Playwright

​Per-session client isolation (stateful servers)

​File and System Servers

​Filesystem Server

​SQLite Server

​Communication Servers

​Slack Server

​Development and API Servers

​GitHub Server

​Map and Location Services

​Amap (高德地图) Server

​Advanced Configuration

​Environment Variable Substitution

​Proxy Configuration (proxychains4)

​Basic Proxy Configuration

​Proxy Configuration Options

​Proxy with Authentication

​Using Custom proxychains4 Configuration

​Group Management

​Group Configuration

​System Routing Settings

​Tool Result Compression

​Best Practices

​Security

MCP Settings Configuration

Configuration Files Overview

Basic MCP Settings Structure

mcp_settings.json

Example Configuration

Server Configuration Options

Top-level fields

`type: "stdio"` (default)

`type: "sse"` or `type: "streamable-http"`

`type: "openapi"`

Common MCP Server Examples

Web and API Servers

Fetch Server

Web Scraping with Playwright

Per-session client isolation (stateful servers)

File and System Servers

Filesystem Server

SQLite Server

Communication Servers

Slack Server

Development and API Servers

GitHub Server

Map and Location Services

Amap (高德地图) Server

Advanced Configuration

Environment Variable Substitution

Proxy Configuration (proxychains4)

Basic Proxy Configuration

Proxy Configuration Options

Proxy with Authentication

Using Custom proxychains4 Configuration

Group Management

Group Configuration

System Routing Settings

Tool Result Compression

Best Practices

Security