> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pcnaid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP settings

> Configure MCP server connections and groups.

# MCP Settings Configuration

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

## Configuration Files Overview

Pcnaid MCP Hub 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 theme={null}
{
  "mcpServers": {
    "server-name": {
      "command": "command-to-run",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}
```

### Example Configuration

```json theme={null}
{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"],
      "env": {
        "USER_AGENT": "PcnaidMCPHub/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

### Required Fields

| Field     | Type   | Description                |
| --------- | ------ | -------------------------- |
| `command` | string | Executable command or path |
| `args`    | array  | Command-line arguments     |

### Optional Fields

| Field | Type   | Default | Description           |
| ----- | ------ | ------- | --------------------- |
| `env` | object | `{}`    | Environment variables |

## Common MCP Server Examples

### Web and API Servers

#### Fetch Server

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

#### Web Scraping with Playwright

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

### File and System Servers

#### Filesystem Server

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

#### SQLite Server

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

### Communication Servers

#### Slack Server

```json theme={null}
{
  "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}"
    }
  }
}
```

#### Email Server

```json theme={null}
{
  "email": {
    "command": "python",
    "args": ["-m", "mcp_server_email"],
    "env": {
      "SMTP_HOST": "smtp.gmail.com",
      "SMTP_PORT": "587",
      "EMAIL_USER": "${EMAIL_USER}",
      "EMAIL_PASSWORD": "${EMAIL_PASSWORD}"
    }
  }
}
```

### Development and API Servers

#### GitHub Server

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

#### Google Drive Server

```json theme={null}
{
  "gdrive": {
    "command": "npx",
    "args": ["-y", "@google/mcp-server-gdrive"],
    "env": {
      "GOOGLE_CLIENT_ID": "${GOOGLE_CLIENT_ID}",
      "GOOGLE_CLIENT_SECRET": "${GOOGLE_CLIENT_SECRET}",
      "GOOGLE_REFRESH_TOKEN": "${GOOGLE_REFRESH_TOKEN}"
    }
  }
}
```

### Map and Location Services

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

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

#### OpenStreetMap Server

```json theme={null}
{
  "osm": {
    "command": "python",
    "args": ["-m", "mcp_server_osm"],
    "env": {
      "OSM_USER_AGENT": "PcnaidMCPHub/1.0"
    }
  }
}
```

## Advanced Configuration

### Environment Variable Substitution

Pcnaid MCP Hub supports environment variable substitution using `${VAR_NAME}` syntax:

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

### Proxy Configuration (proxychains4)

Pcnaid MCP Hub 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 theme={null}
{
  "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 theme={null}
{
  "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 theme={null}
{
  "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>

## Group Management

### Group Configuration

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

{/* ### Configuration Validation

Pcnaid MCP Hub validates configurations on startup and reload:

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

## Best Practices

### Security

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

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

{/* ### 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"
   }
 }
 ``` */}

{/* ## Troubleshooting

### Common Issues

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

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

{/* ### Debug Configuration

Enable debug mode for detailed logging:

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

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