> ## 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 设置配置

> 配置 MCPHub 的 MCP 服务器及其设置

# MCP 设置配置

本指南说明如何使用 `mcp_settings.json` 文件和相关配置在 MCPHub 中配置 MCP 服务器。

## 配置文件概述

MCPHub 使用几个配置文件：

* **`mcp_settings.json`**：主要的 MCP 服务器配置
* **`servers.json`**：服务器元数据和分组
* **`.env`**：环境变量和密钥

## 基本 MCP 设置结构

### mcp\_settings.json

```json theme={null}
{
  "mcpServers": {
    "server-name": {
      "command": "command-to-run",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      },
      "cwd": "/working/directory",
      "timeout": 30000,
      "restart": true
    }
  }
}
```

### 示例配置

```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"],
      "timeout": 60000
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
        "SLACK_TEAM_ID": "${SLACK_TEAM_ID}"
      }
    }
  }
}
```

## 服务器配置选项

### 必需字段

| 字段 | 类型 | 描述 |
| - | - | - |
| `command` | string | 可执行命令或路径 |
| `args` | array | 命令行参数 |

### 可选字段

| 字段 | 类型 | 默认值 | 描述 |
| - | - | - | - |
| `env` | object | `{}` | 环境变量 |
| `cwd` | string | `process.cwd()` | 工作目录 |
| `timeout` | number | `30000` | 启动超时（毫秒） |
| `restart` | boolean | `true` | 失败时自动重启 |
| `maxRestarts` | number | `5` | 最大重启次数 |
| `restartDelay` | number | `5000` | 重启间延迟（毫秒） |
| `stdio` | string | `pipe` | stdio 配置 |
| `perSessionClient` | boolean | `false` | 为每个下游 MCP 会话创建独立的上游客户端，而不是在所有会话间共享同一个连接。适用于 Playwright 等有状态服务器。参见[会话级客户端隔离](#会话级客户端隔离有状态服务器)。 |

### `type: "openapi"`

| 字段 | 类型 | 必需 | 描述 |
| - | - | - | - |
| `openapi.url` | string | `url`/`schema` 二选一 | MCPHub 将下载的 OpenAPI 文档 URL。 |
| `openapi.schema` | object | `url`/`schema` 二选一 | 内联的 OpenAPI 文档。 |
| `headers` | object | 否 | 应用于所有出站请求的静态请求头，包括文档下载本身。 |
| `openapi.passthroughHeaders` | string\[] | 否 | 从调用方转发到上游的请求头名称。 |

每个字段的权威定义见 [src/types/index.ts](src/types/index.ts) 中的 `ServerConfig` 类型；如需此处未描述的行为，请查阅该类型。

<Note>
  受保护的 `openapi.url` 会通过 MCPHub 的已认证客户端下载，因此配置的 `headers` 与 OpenAPI `security` 凭证（HTTP Basic/Bearer、API Key、OAuth2 令牌）会用于该次拉取的认证。凭证仅作用于文档所在源，不会转发给外部 `$ref` 解析或跨源重定向。若受保护的文档引用了同样需要认证的外部 `$ref`，请改用 `openapi.schema` 内联文档。
</Note>

## 常见 MCP 服务器示例

### Web 和 API 服务器

#### Fetch 服务器

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

#### 使用 Playwright 进行网页抓取

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

### 会话级客户端隔离（有状态服务器）

默认情况下，MCPHub 为每个服务器仅保持**一个**上游连接，并在所有下游 MCP 会话间共享。
对于有状态服务器来说，这意味着所有客户端共享同一份状态——以 Playwright 为例，每个会话都会
操作同一个浏览器实例及其标签页。

设置 `perSessionClient: true` 可以让 MCPHub 改为**为每个下游会话创建独立的上游客户端**。
每个会话拥有各自的连接（对于 stdio 服务器，还会拥有各自的子进程），在首次工具调用时惰性创建，
并在会话结束时自动销毁。

<Note>
  `perSessionClient` 是 **MCPHub 侧**的设置：它控制 MCPHub 打开多少个上游连接。它与 Playwright
  MCP 自身的 `--isolated` 标志不同，后者控制 Playwright 侧的浏览器配置隔离。二者天然互补——同时
  启用即可获得完全隔离的浏览器会话。
</Note>

```json theme={null}
{
  "mcpServers": {
    "playwright": {
      "type": "streamable-http",
      "url": "http://playwright-mcp:3000/mcp",
      "perSessionClient": true
    }
  }
}
```

或者使用本地启动并带有 `--isolated` 标志的 Playwright MCP：

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

<Tip>
  仅对真正持有会话级状态的服务器启用 `perSessionClient`。它会让上游连接（以及 stdio 子进程）
  数量随并发会话数成倍增长，因此对无状态服务器请保持关闭。
</Tip>

### MCP 2026-07-28 的路由请求头

新版请求使用 `MCP-Protocol-Version: 2026-07-28`，并携带与 JSON-RPC 方法一致的
`Mcp-Method`。`tools/call` 和 `prompts/get` 还需要与 `params.name` 一致的
`Mcp-Name`；`resources/read` 则需要与 `params.uri` 一致。列表方法无需
`Mcp-Name`。SDK v2 HTTP 客户端会自动设置这些请求头。

例如，向 `/mcp` 调用 `params.name` 为 `my-server-my-tool` 的工具时发送：

```http theme={null}
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: my-server-my-tool
```

这些请求头与正常的 JSON-RPC 请求体一起发送，请求体仍需包含新版协议的
`params._meta` 协议版本与客户端能力信息。请求头不选择分组，也不授予访问权限；
可访问的服务器仍由 URL 和 bearer 权限决定。使用服务器专属 URL 时，请求体与
请求头都应使用该 URL 下暴露的工具名称。非 ASCII 名称在 `Mcp-Name` 中使用
SDK 的 `=?base64?<UTF-8 Base64>?=` 编码。

缺失必需请求头、请求头与请求体不一致或名称编码非法时，在执行前返回 HTTP 400
和 JSON-RPC 错误 `-32020`。旧版 `2025-11-25` 请求继续使用原有握手与会话机制，
无需这些路由请求头。

### MCP 2026-07-28 的有状态工具

新版 MCP 请求不创建下游传输会话。调用启用 `perSessionClient: true` 或 OpenAPI
`cookieSession: true` 的工具时，请开启 bearer 认证，并在同一应用工作流的每个请求中
携带客户端生成的 UUID v4：

```http theme={null}
Authorization: Bearer <your-key>
X-MCPHub-State-Id: 65b523af-e4d0-4d99-8e06-461a62a14967
```

`X-MCPHub-State-Id` 是 MCPHub 扩展，与 `Mcp-Session-Id` 和 MCP 握手独立。
只有 bearer 凭据、用户和路由均相同的请求才会复用同一状态标识对应的独立上游客户端
和 cookie jar。不同工作流应使用不同 UUID。

无法设置该扩展的已认证 OpenAI/ChatGPT 工具调用可以省略它，并使用 ChatGPT 工具调用中
客户端声明的 `_meta["openai/session"]` 会话提示。MCPHub 会先对该值做哈希，再仅用于状态
关联；它不会参与认证或授权，复用范围仍由已验证的 bearer 凭据、用户和路由限制。如果
显式 `X-MCPHub-State-Id` 已提供但非法，则直接失败而不会回退。如果两个可用关联值都缺失，
有状态工具返回工具错误；其他工具无需状态标识。

状态只保存在单个 MCPHub 进程的内存中，空闲 30 分钟后回收，执行中的调用会保留状态
直到完成。回收和关闭进程时会关闭独立上游客户端并清空 cookie jar。每个进程最多容纳
1,000 个新版状态作用域，超出时返回工具错误，等待容量释放后可重试。进程重启、状态
过期、bearer 更换或路由变化后需要重新建立应用状态。多副本部署需要粘性路由。
旧版 `2025-11-25` 客户端继续使用已有的下游会话生命周期。

### 文件和系统服务器

#### 文件系统服务器

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

#### SQLite 服务器

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

### 通信服务器

#### Slack 服务器

```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}"
    }
  }
}
```

#### 邮件服务器

```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}"
    }
  }
}
```

### 开发和 API 服务器

#### GitHub 服务器

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

#### Google Drive 服务器

```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}"
    }
  }
}
```

### 地图和位置服务

#### 高德地图服务器

```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 服务器

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

## 高级配置

### 环境变量替换

MCPHub 支持使用 `${VAR_NAME}` 语法进行环境变量替换：

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

可以使用 `${VAR_NAME:default}` 指定默认值：

```json theme={null}
{
  "timeout": "${MCP_TIMEOUT:30000}",
  "maxRestarts": "${MCP_MAX_RESTARTS:5}"
}
```

### 条件配置

根据环境使用不同配置：

```json theme={null}
{
  "mcpServers": {
    "database": {
      "command": "python",
      "args": ["-m", "db_server"],
      "env": {
        "DB_URL": "${NODE_ENV:development == 'production' ? DB_URL : DEV_DB_URL}"
      }
    }
  }
}
```

### 自定义服务器脚本

#### 本地 Python 服务器

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

#### 本地 Node.js 服务器

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

## 服务器元数据配置

### servers.json

使用服务器元数据补充 `mcp_settings.json`：

```json theme={null}
{
  "servers": {
    "fetch": {
      "name": "Fetch 服务器",
      "description": "用于网络请求的 HTTP 客户端",
      "category": "web",
      "tags": ["http", "api", "web"],
      "version": "1.0.0",
      "author": "MCPHub 团队",
      "documentation": "https://docs.mcphub.com/servers/fetch",
      "enabled": true
    },
    "playwright": {
      "name": "Playwright 浏览器",
      "description": "网页自动化和抓取",
      "category": "automation",
      "tags": ["browser", "scraping", "automation"],
      "version": "2.0.0",
      "enabled": true
    }
  },
  "groups": {
    "web-tools": {
      "name": "网页工具",
      "description": "用于网页交互的工具",
      "servers": ["fetch", "playwright"],
      "access": "public"
    },
    "admin-tools": {
      "name": "管理工具",
      "description": "管理实用程序",
      "servers": ["filesystem", "database"],
      "access": "admin"
    }
  }
}
```

## 组管理

### 组配置

```json theme={null}
{
  "groups": {
    "production": {
      "name": "生产工具",
      "description": "稳定的生产服务器",
      "servers": ["fetch", "slack", "github"],
      "access": "authenticated",
      "rateLimit": {
        "requestsPerMinute": 100,
        "burstLimit": 20
      }
    },
    "experimental": {
      "name": "实验功能",
      "description": "测试版和实验性服务器",
      "servers": ["experimental-ai", "beta-search"],
      "access": "admin",
      "enabled": false
    }
  }
}
```

### 访问控制

| 访问级别 | 描述 |
| - | - |
| `public` | 无需认证 |
| `authenticated` | 需要有效的 JWT 令牌 |
| `admin` | 需要管理员角色 |
| `custom` | 自定义权限逻辑 |

## 动态配置

### 热重载

MCPHub 支持配置热重载：

```bash theme={null}
# 不重启重新加载配置
curl -X POST http://localhost:3000/api/admin/reload-config \
  -H "Authorization: Bearer your-admin-token"
```

### 配置验证

MCPHub 在启动和重新加载时验证配置：

```json theme={null}
{
  "validation": {
    "strict": true,
    "allowUnknownServers": false,
    "requireDocumentation": true
  }
}
```

## 工具结果压缩

MCPHub 可以在工具结果返回 MCP 客户端前，透明压缩较大的文本结果。它适合处理大型日志、diff、搜索输出、JSON 数组或长文本，避免这些内容占用过多模型上下文。

工具结果压缩默认关闭。可以在 **设置 → 工具结果压缩** 中实时开关，也可以在 `systemConfig.toolResultCompression` 下配置：

```json theme={null}
{
  "systemConfig": {
    "toolResultCompression": {
      "enabled": false,
      "minTokens": 2000,
      "maxOutputTokens": 1200,
      "strategy": "auto"
    }
  }
}
```

| 字段 | 类型 | 默认值 | 描述 |
| - | - | - | - |
| `enabled` | boolean | `false` | 是否对成功的工具结果启用透明压缩。 |
| `minTokens` | number | `2000` | 单个文本块的估算 token 数达到或超过该阈值时才会压缩。 |
| `maxOutputTokens` | number | `1200` | 每个压缩后文本块的目标 token 预算。 |
| `strategy` | `"auto" \| "json" \| "log" \| "search" \| "diff" \| "text"` | `"auto"` | 压缩策略。`auto` 会自动识别常见结构化输出。 |

压缩只作用于成功的工具响应。带有 `isError: true` 的响应会原样返回，非文本内容块会被保留，每个文本块会独立判断是否需要压缩。MCPHub 压缩结果时会在文本开头加入类似下面的标记：

```text theme={null}
[mcphub:compressed-tool-result strategy=log original_tokens=9000 compressed_tokens=1200 omitted_lines=240]
```

活动日志仍记录上游工具的原始输出，压缩只发生在返回 MCP 客户端之前，因此运维人员仍可在 MCPHub 中查看完整结果。

## 最佳实践

### 安全

1. **对敏感数据使用环境变量**：

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

2. **限制服务器权限**：
   ```json theme={null}
   {
     "filesystem": {
       "command": "npx",
       "args": ["-y", "@modelcontextprotocol/server-filesystem", "/restricted/path"],
       "env": {
         "READONLY": "true"
       }
     }
   }
   ```

### 性能

1. **设置适当的超时**：

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

2. **资源限制**：
   ```json theme={null}
   {
     "env": {
       "NODE_OPTIONS": "--max-old-space-size=512",
       "MEMORY_LIMIT": "512MB"
     }
   }
   ```

### 监控

1. **启用健康检查**：

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

2. **日志配置**：
   ```json theme={null}
   {
     "env": {
       "LOG_LEVEL": "info",
       "LOG_FORMAT": "json"
     }
   }
   ```

## 故障排除

### 常见问题

**服务器无法启动**：检查命令和参数

```bash theme={null}
# 手动测试命令
uvx mcp-server-fetch
```

**找不到环境变量**：验证 `.env` 文件

```bash theme={null}
# 检查环境
printenv | grep API_KEY
```

**权限错误**：检查文件权限和路径

```bash theme={null}
# 验证可执行权限
ls -la /path/to/server
```

### 调试配置

启用调试模式进行详细日志记录：

```json theme={null}
{
  "debug": {
    "enabled": true,
    "logLevel": "debug",
    "includeEnv": false,
    "logStartup": true
  }
}
```

### 验证错误

常见验证错误和解决方案：

1. **缺少必需字段**：添加 `command` 和 `args`
2. **无效超时**：使用数字，不是字符串
3. **找不到环境变量**：检查 `.env` 文件
4. **找不到命令**：验证安装和 PATH

这个全面的指南涵盖了在 MCPHub 中为各种用例和环境配置 MCP 服务器的所有方面。

### Stdio 响应缓冲区

将 `options.maxBufferSize` 设置为以字节为单位的正安全整数，可接收更大的 stdio 响应：

```json theme={null}
{
  "type": "stdio",
  "command": "node",
  "args": ["server.js"],
  "options": { "maxBufferSize": 268435456 }
}
```

省略该选项时保留 SDK 默认值 10 MiB（10485760 字节）。上限用于读取包含 MCP 消息封装的序列化数据的缓冲区。响应超过上限会关闭传输连接。提高上限会允许使用更多内存，请按服务器需求设置有限上限。零、负数、小数和非有限值均被拒绝。该选项不会改变 HTTP 传输或 SDK 处理大消息的性能。

## 放行内网上游网络

管理员可在设置页维护**允许访问的上游 CIDR 范围**，JSON 存储模式也可配置 `systemConfig.network.allowedCidrs`：

```json theme={null}
{
  "systemConfig": {
    "network": {
      "allowedCidrs": ["192.168.1.0/24", "fd00:1234::/64"]
    }
  }
}
```

默认为空列表。配置后，所有用户的上游 MCP（SSE 和 Streamable HTTP）、OpenAPI 及上游 OAuth 请求均可访问这些范围。公网地址仍可访问，管理员拥有的服务器保留已有的不受限内网访问权限。服务器可见性与共享权限不受影响。

每项必须是带前缀长度的 IPv4 或 IPv6 地址，例如 `/32` 表示单个 IPv4 地址，`/128` 表示单个 IPv6 地址。系统检查全部 DNS 结果、每次重定向目标及建立连接时的 DNS 结果。删除范围会影响后续请求，但不会关闭已有连接或清除缓存。匿名 OAuth 客户端元数据（CIMD）URL 仍仅允许公网地址。

只有管理员可调用 `PUT /api/system-config`，请求体为 `{"network":{"allowedCidrs":["192.168.1.0/24"]}}`。传入空数组可清空白名单，非法列表返回 HTTP 400 且不会保存。数据库模式请通过管理界面或 API 配置，该字段持久化到系统配置表。

请仅放行必要的最小范围。`0.0.0.0/0` 或 `::/0` 等过大的范围也会放行回环地址、云元数据端点等敏感内网目标。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.