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

# MCP Settings Configuration

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

### Development and API Servers

#### GitHub Server

```json theme={null}
{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_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}"
    }
  }
}
```

<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 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)

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

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

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

```text theme={null}
[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

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 MCPHub for various use cases and environments.