---
title: 'MCP Settings Configuration'
description: 'Configure MCP servers and their settings for MCPHub'
---

# 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

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

### Example Configuration

```json
{
  "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 pings. |
| `keepAliveInterval` | number | no | Keep-alive interval in milliseconds. Defaults to `60000`. |
| `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](src/types/index.ts) — consult it if you need behavior not described here.

## Common MCP Server Examples

### Web and API Servers

#### Fetch Server

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

#### Web Scraping with Playwright

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

### File and System Servers

#### Filesystem Server

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

#### SQLite Server

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

### Communication Servers

#### Slack Server

```json
{
  "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

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

### Map and Location Services

#### Amap (高德地图) Server

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

<Tip>
  Looking for more servers? The bundled [Market catalog](https://docs.mcphub.app/features/server-management) in the dashboard lists hundreds of known MCP servers with copy-paste-ready configurations.
</Tip>

## Advanced Configuration

### Environment Variable Substitution

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

```json
{
  "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).

<Note>
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`
</Note>

#### Basic Proxy Configuration

```json
{
  "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

```json
{
  "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:

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

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

{/* ### Custom Server Scripts

#### Local Python Server

```json
{
  "custom-python": {
    "command": "python",
    "args": ["./servers/custom_server.py"],
    "cwd": "/app/custom-servers",
    "env": {
      "PYTHONPATH": "/app/custom-servers",
      "CONFIG_FILE": "./config.json"
    }
  }
}
```

#### Local Node.js Server

```json
{
  "custom-node": {
    "command": "node",
    "args": ["./servers/custom-server.js"],
    "cwd": "/app/custom-servers",
    "env": {
      "NODE_ENV": "production"
    }
  }
}
```

## Server Metadata Configuration

### servers.json

Complement `mcp_settings.json` with server metadata:

```json
{
  "servers": {
    "fetch": {
      "name": "Fetch Server",
      "description": "HTTP client for web requests",
      "category": "web",
      "tags": ["http", "api", "web"],
      "version": "1.0.0",
      "author": "MCPHub Team",
      "documentation": "https://docs.mcphub.com/servers/fetch",
      "enabled": true
    },
    "playwright": {
      "name": "Playwright Browser",
      "description": "Web automation and scraping",
      "category": "automation",
      "tags": ["browser", "scraping", "automation"],
      "version": "2.0.0",
      "enabled": true
    }
  },
  "groups": {
    "web-tools": {
      "name": "Web Tools",
      "description": "Tools for web interaction",
      "servers": ["fetch", "playwright"],
      "access": "public"
    },
    "admin-tools": {
      "name": "Admin Tools",
      "description": "Administrative utilities",
      "servers": ["filesystem", "database"],
      "access": "admin"
    }
  }
}
``` */}

## Group Management

### Group Configuration

```json
{
  "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"]
    }
  }
}
```

{/* ### Access Control

| Access Level    | Description                |
| --------------- | -------------------------- |
| `public`        | No authentication required |
| `authenticated` | Valid JWT token required   |
| `admin`         | Admin role required        |
| `custom`        | Custom permission logic    |

## Dynamic Configuration

### Hot Reloading

MCPHub supports hot reloading of configurations:

```bash
# Reload configurations without restart
curl -X POST http://localhost:3000/api/admin/reload-config \
  -H "Authorization: Bearer your-admin-token"
``` */}

{/* ### Configuration Validation

MCPHub validates configurations on startup and reload:

```json
{
  "validation": {
    "strict": true,
    "allowUnknownServers": false,
    "requireDocumentation": true
  }
}
``` */}

## System Routing Settings

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

```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.

## Best Practices

### Security

1. **Use environment variables** for sensitive data:

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

{/* 2. **Limit server permissions**:
   ```json
   {
     "filesystem": {
       "command": "npx",
       "args": ["-y", "@modelcontextprotocol/server-filesystem", "/restricted/path"],
       "env": {
         "READONLY": "true"
       }
     }
   }
   ``` */}

{/* ### Performance

1. **Set appropriate timeouts**:

   ```json
   {
     "timeout": 30000,
     "maxRestarts": 3,
     "restartDelay": 5000
   }
   ```

2. **Resource limits**:
   ```json
   {
     "env": {
       "NODE_OPTIONS": "--max-old-space-size=512",
       "MEMORY_LIMIT": "512MB"
     }
   }
   ``` */}

{/* ### Monitoring

1. **Enable health checks**:

   ```json
   {
     "healthCheck": {
       "enabled": true,
       "interval": 30000,
       "timeout": 5000
     }
   }
   ```

2. **Logging configuration**:
   ```json
   {
     "env": {
       "LOG_LEVEL": "info",
       "LOG_FORMAT": "json"
     }
   }
   ``` */}

{/* ## Troubleshooting

### Common Issues

**Server won't start**: Check command and arguments

```bash
# Test command manually
uvx mcp-server-fetch
``` */}

{/* **Environment variables not found**: Verify `.env` file

```bash
# Check environment
printenv | grep API_KEY
```

**Permission errors**: Check file permissions and paths

```bash
# Verify executable permissions
ls -la /path/to/server
``` */}

{/* ### Debug Configuration

Enable debug mode for detailed logging:

```json
{
  "debug": {
    "enabled": true,
    "logLevel": "debug",
    "includeEnv": false,
    "logStartup": true
  }
}
``` */}
{/* 
### Validation Errors

Common validation errors and solutions:

1. **Missing required fields**: Add `command` and `args`
2. **Invalid timeout**: Use number, not string
3. **Environment variable not found**: Check `.env` file
4. **Command not found**: Verify installation and PATH */}

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