配置深入指南

1MCP 代理为运行时行为、传输设置、身份验证等提供了广泛的配置选项。本指南涵盖了控制代理如何运行的命令行标志和环境变量。

有关 MCP 服务器配置（后端服务器、环境管理、进程控制），请参阅 MCP 服务器参考。

配置方法

代理支持三种配置方法，按以下优先级顺序应用：

环境变量：最高优先级，适用于容器化部署
命令行标志：在运行时覆盖设置
配置文件：基础配置（在 MCP 服务器参考中介绍）

命令行选项

所有可用的命令行选项及其对应的环境变量：

选项 (CLI)	环境变量	描述	默认值
`--transport`, `-t`	`ONE_MCP_TRANSPORT`	选择传输类型（"stdio"、"http" 或 "sse"）	"http"
`--config`, `-c`	`ONE_MCP_CONFIG`	使用特定的配置文件
`--config-dir`, `-d`	`ONE_MCP_CONFIG_DIR`	配置目录路径（覆盖默认配置位置）
`--port`, `-P`	`ONE_MCP_PORT`	更改 HTTP 端口	3050
`--host`, `-H`	`ONE_MCP_HOST`	更改 HTTP 主机	localhost
`--external-url`, `-u`	`ONE_MCP_EXTERNAL_URL`	OAuth 回调和公共 URL 的外部 URL（例如 https://example.com）
`--trust-proxy`	`ONE_MCP_TRUST_PROXY`	客户端 IP 检测的信任代理配置（布尔值、IP、CIDR、预设）	"loopback"
`--tags`, `-g`	`ONE_MCP_TAGS`	按标签过滤服务器（逗号分隔，OR 逻辑）⚠️ 已弃用 - 请使用 --tag-filter
`--tag-filter`, `-f`	`ONE_MCP_TAG_FILTER`	高级标签过滤表达式（and/or/not 逻辑）
`--pagination`, `-p`	`ONE_MCP_PAGINATION`	为客户端/服务器列表启用分页（布尔值）	false
`--enable-auth`	`ONE_MCP_ENABLE_AUTH`	启用身份验证（OAuth 2.1）	false
`--enable-scope-validation`	`ONE_MCP_ENABLE_SCOPE_VALIDATION`	启用基于标签的范围验证（布尔值）	true
`--enable-enhanced-security`	`ONE_MCP_ENABLE_ENHANCED_SECURITY`	启用增强安全中间件（布尔值）	false
`--session-ttl`	`ONE_MCP_SESSION_TTL`	会话过期时间（分钟）（数字）	1440
`--session-storage-path`	`ONE_MCP_SESSION_STORAGE_PATH`	自定义会话存储目录路径（字符串）
`--rate-limit-window`	`ONE_MCP_RATE_LIMIT_WINDOW`	OAuth 速率限制窗口（分钟）（数字）	15
`--rate-limit-max`	`ONE_MCP_RATE_LIMIT_MAX`	每个 OAuth 速率限制窗口的最大请求数（数字）	100
`--enable-async-loading`	`ONE_MCP_ENABLE_ASYNC_LOADING`	启用异步 MCP 服务器加载（布尔值）	false
`--enable-config-reload`	`ONE_MCP_ENABLE_CONFIG_RELOAD`	启用配置文件热重载（布尔值）	true
`--config-reload-debounce`	`ONE_MCP_CONFIG_RELOAD_DEBOUNCE`	配置重载防抖时间（毫秒）（数字）	500
`--enable-env-substitution`	`ONE_MCP_ENABLE_ENV_SUBSTITUTION`	在配置文件中启用环境变量替换（布尔值）	true
`--enable-session-persistence`	`ONE_MCP_ENABLE_SESSION_PERSISTENCE`	启用 HTTP 会话持久化（布尔值）	true
`--session-persist-requests`	`ONE_MCP_SESSION_PERSIST_REQUESTS`	会话持久化请求阈值（数字）	100
`--session-persist-interval`	`ONE_MCP_SESSION_PERSIST_INTERVAL`	会话持久化间隔（分钟）（数字）	5
`--session-background-flush`	`ONE_MCP_SESSION_BACKGROUND_FLUSH`	会话后台刷新间隔（秒）（数字）	60
`--enable-client-notifications`	`ONE_MCP_ENABLE_CLIENT_NOTIFICATIONS`	启用实时客户端通知（布尔值）	true
`--health-info-level`	`ONE_MCP_HEALTH_INFO_LEVEL`	健康端点信息详细级别（"full"、"basic"、"minimal"）	"minimal"
`--log-level`	`ONE_MCP_LOG_LEVEL`	设置日志级别（"debug"、"info"、"warn"、"error"）	"info"
`--log-file`	`ONE_MCP_LOG_FILE`	除控制台外还将日志写入文件（仅对 stdio 传输禁用控制台日志记录）
`--help`, `-h`		显示帮助

配置类别

传输选项

控制代理与客户端和后端服务器的通信方式。

--transport, -t <type>

值：stdio、http、sse（已弃用）
默认值：http
环境变量：ONE_MCP_TRANSPORT

示例：

bash

# HTTP 传输（默认）
npx -y @1mcp/agent --transport http

# 用于直接 MCP 客户端集成的 Stdio 传输
npx -y @1mcp/agent --transport stdio

# 使用环境变量
ONE_MCP_TRANSPORT=stdio npx -y @1mcp/agent

网络配置

配置网络访问的 HTTP 服务器设置。

--port, -P <port>

默认值：3050
环境变量：ONE_MCP_PORT

--host, -H <host>

默认值：localhost
环境变量：ONE_MCP_HOST

--external-url, -u <url>

用途：OAuth 回调和公共 URL 的外部 URL
环境变量：ONE_MCP_EXTERNAL_URL

示例：

bash

# 自定义端口和主机
npx -y @1mcp/agent --port 3051 --host 0.0.0.0

# 用于反向代理设置的外部 URL
npx -y @1mcp/agent --external-url https://mcp.example.com

# 用于 Docker 的环境变量
ONE_MCP_HOST=0.0.0.0 ONE_MCP_PORT=3051 npx -y @1mcp/agent

配置管理

控制配置文件位置和加载行为。

--config, -c <path>

用途：使用特定的配置文件
环境变量：ONE_MCP_CONFIG

--config-dir, -d <path>

用途：配置目录的路径（覆盖默认位置）
环境变量：ONE_MCP_CONFIG_DIR

示例：

bash

# 使用特定的配置文件
npx -y @1mcp/agent --config ./my-config.json

# 使用自定义配置目录
npx -y @1mcp/agent --config-dir ./project-config

# 配置目录的环境变量
ONE_MCP_CONFIG_DIR=/opt/1mcp/config npx -y @1mcp/agent

安全配置

身份验证、授权和安全功能。

--enable-auth

用途：启用 OAuth 2.1 身份验证
默认值：false
环境变量：ONE_MCP_ENABLE_AUTH

--enable-scope-validation

用途：启用基于标签的范围验证
默认值：true
环境变量：ONE_MCP_ENABLE_SCOPE_VALIDATION

--enable-enhanced-security

用途：启用增强安全中间件
默认值：false
环境变量：ONE_MCP_ENABLE_ENHANCED_SECURITY

会话管理：

--session-ttl <minutes>：会话过期时间（默认：1440）
--session-storage-path <path>：自定义会话存储目录
--rate-limit-window <minutes>：OAuth 速率限制窗口（默认：15）
--rate-limit-max <requests>：每个窗口的最大请求数（默认：100）

示例：

bash

# 启用带增强安全性的身份验证
npx -y @1mcp/agent --enable-auth --enable-enhanced-security

# 自定义会话配置
npx -y @1mcp/agent \
  --enable-auth \
  --session-ttl 720 \
  --rate-limit-window 10 \
  --rate-limit-max 50

# 环境变量
ONE_MCP_ENABLE_AUTH=true \
ONE_MCP_ENABLE_ENHANCED_SECURITY=true \
npx -y @1mcp/agent

网络安全

为反向代理部署配置信任代理设置。

--trust-proxy <config>

默认值："loopback"
环境变量：ONE_MCP_TRUST_PROXY
值：
- true：信任所有代理
- false：不信任代理
- IP 地址：信任特定 IP
- CIDR：信任 IP 范围
- "loopback"：仅信任回环地址

示例：

bash

# 信任所有代理（CDN/Cloudflare）
npx -y @1mcp/agent --trust-proxy true

# 信任特定代理 IP
npx -y @1mcp/agent --trust-proxy 192.168.1.100

# 信任 IP 范围
npx -y @1mcp/agent --trust-proxy 10.0.0.0/8

有关详细的信任代理配置，请参阅 信任代理参考。

服务器过滤

控制加载和可用的后端 MCP 服务器。

--tags, -g <tags> ⚠️ 已弃用

用途：按标签过滤服务器（逗号分隔，OR 逻辑）
环境变量：ONE_MCP_TAGS

--tag-filter, -f <expression> ✅ 推荐

用途：具有布尔逻辑的高级标签过滤表达式
环境变量：ONE_MCP_TAG_FILTER

标签过滤器语法：

tag1,tag2：OR 逻辑（任一标签）
tag1+tag2：AND 逻辑（两个标签）
(tag1,tag2)+tag3：复杂表达式
tag1 and tag2 and not tag3：自然语言语法

示例：

bash

# 简单 OR 过滤（已弃用）
npx -y @1mcp/agent --tags "network,filesystem"

# 高级过滤（推荐）
npx -y @1mcp/agent --tag-filter "network+api"
npx -y @1mcp/agent --tag-filter "(web,api)+production-test"
npx -y @1mcp/agent --tag-filter "web and api and not test"

# 环境变量
ONE_MCP_TAG_FILTER="network+api" npx -y @1mcp/agent

性能选项

控制性能和资源使用行为。

--enable-async-loading

用途：启用异步 MCP 服务器加载
默认值：false
环境变量：ONE_MCP_ENABLE_ASYNC_LOADING

--pagination, -p

用途：为客户端/服务器列表启用分页
默认值：false
环境变量：ONE_MCP_PAGINATION

示例：

bash

# 启用异步加载以加快启动速度
npx -y @1mcp/agent --enable-async-loading

# 为大型服务器列表启用分页
npx -y @1mcp/agent --pagination

# 环境变量
ONE_MCP_ENABLE_ASYNC_LOADING=true \
ONE_MCP_PAGINATION=true \
npx -y @1mcp/agent

配置重载

控制配置文件热重载行为以实现无缝更新。

--enable-config-reload

用途：启用配置文件热重载
默认值：true
环境变量：ONE_MCP_ENABLE_CONFIG_RELOAD

--config-reload-debounce <毫秒>

用途：配置重载的防抖时间，防止过多重载
默认值：500
环境变量：ONE_MCP_CONFIG_RELOAD_DEBOUNCE

示例：

bash

# 启用配置重载并自定义防抖时间
npx -y @1mcp/agent --enable-config-reload --config-reload-debounce 1000

# 禁用配置重载（适用于生产环境稳定性）
npx -y @1mcp/agent --enable-config-reload false

# 环境变量
ONE_MCP_ENABLE_CONFIG_RELOAD=true \
ONE_MCP_CONFIG_RELOAD_DEBOUNCE=200 \
npx -y @1mcp/agent

环境变量替换

在配置文件中使用环境变量实现动态配置。

--enable-env-substitution

用途：在配置文件中启用环境变量替换
默认值：true
环境变量：ONE_MCP_ENABLE_ENV_SUBSTITUTION

用法：

启用后，您可以在 JSON 配置文件中使用 ${VAR_NAME} 语法：

json

{
  "servers": [
    {
      "name": "database",
      "command": "python",
      "args": ["${DB_SERVER_PATH}", "--port", "${DB_PORT}"]
    }
  ],
  "auth": {
    "sessionStoragePath": "${SESSION_STORAGE_DIR}"
  }
}

示例：

bash

# 启用环境变量替换（默认）
npx -y @1mcp/agent --enable-env-substitution

# 禁用环境变量替换
npx -y @1mcp/agent --enable-env-substitution false

# 环境变量
DB_SERVER_PATH=/opt/db-server \
DB_PORT=5432 \
SESSION_STORAGE_DIR=/var/lib/1mcp/sessions \
ONE_MCP_ENABLE_ENV_SUBSTITUTION=true \
npx -y @1mcp/agent

会话持久化

控制 HTTP 会话持久化以提高服务器重启时的可靠性。

--enable-session-persistence

用途：启用 HTTP 会话持久化
默认值：true
环境变量：ONE_MCP_ENABLE_SESSION_PERSISTENCE

--session-persist-requests <数字>

用途：触发会话持久化前的请求数量
默认值：100
环境变量：ONE_MCP_SESSION_PERSIST_REQUESTS

--session-persist-interval <分钟>

用途：自动会话持久化的时间间隔（分钟）
默认值：5
环境变量：ONE_MCP_SESSION_PERSIST_INTERVAL

--session-background-flush <秒>

用途：会话持久化的后台刷新间隔（秒）
默认值：60
环境变量：ONE_MCP_SESSION_BACKGROUND_FLUSH

示例：

bash

# 启用会话持久化并使用默认设置
npx -y @1mcp/agent --enable-session-persistence

# 自定义会话持久化设置
npx -y @1mcp/agent \
  --enable-session-persistence \
  --session-persist-requests 50 \
  --session-persist-interval 10 \
  --session-background-flush 30

# 禁用会话持久化
npx -y @1mcp/agent --enable-session-persistence false

# 环境变量
ONE_MCP_ENABLE_SESSION_PERSISTENCE=true \
ONE_MCP_SESSION_PERSIST_REQUESTS=200 \
ONE_MCP_SESSION_PERSIST_INTERVAL=15 \
npx -y @1mcp/agent

客户端通知

控制向连接的客户端发送关于功能变更的实时通知。

--enable-client-notifications

用途：启用实时客户端通知
默认值：true
环境变量：ONE_MCP_ENABLE_CLIENT_NOTIFICATIONS

示例：

bash

# 启用客户端通知（默认）
npx -y @1mcp/agent --enable-client-notifications

# 禁用客户端通知
npx -y @1mcp/agent --enable-client-notifications false

# 环境变量
ONE_MCP_ENABLE_CLIENT_NOTIFICATIONS=true npx -y @1mcp/agent

监控和健康

配置健康检查端点和信息详细级别。

--health-info-level <level>

值："full"、"basic"、"minimal"
默认值："minimal"
环境变量：ONE_MCP_HEALTH_INFO_LEVEL

级别：

minimal：仅基本健康状态
basic：带基本指标的健康状态
full：完整的系统信息和指标

示例：

bash

# 用于监控的完整健康信息
npx -y @1mcp/agent --health-info-level full

# 基本健康信息
npx -y @1mcp/agent --health-info-level basic

# 环境变量
ONE_MCP_HEALTH_INFO_LEVEL=full npx -y @1mcp/agent

有关详细的健康检查信息，请参阅 健康检查参考。

日志配置

控制日志输出、级别和目标。

--log-level <level>

值："debug"、"info"、"warn"、"error"
默认值："info"
环境变量：ONE_MCP_LOG_LEVEL

--log-file <path>

用途：除控制台外还将日志写入文件
注意：仅对 stdio 传输禁用控制台日志记录
环境变量：ONE_MCP_LOG_FILE

示例：

bash

# 调试日志
npx -y @1mcp/agent --log-level debug

# 记录到文件
npx -y @1mcp/agent --log-file /var/log/1mcp.log

# 组合日志配置
npx -y @1mcp/agent --log-level debug --log-file app.log

# 环境变量
ONE_MCP_LOG_LEVEL=debug npx -y @1mcp/agent
ONE_MCP_LOG_FILE=/var/log/1mcp.log npx -y @1mcp/agent

从传统 LOG_LEVEL 迁移： 传统的 LOG_LEVEL 环境变量仍然受支持，但已弃用：

bash

# ⚠️ 已弃用（显示警告）
LOG_LEVEL=debug npx -y @1mcp/agent

# ✅ 推荐
ONE_MCP_LOG_LEVEL=debug npx -y @1mcp/agent
# 或
npx -y @1mcp/agent --log-level debug

环境变量参考

所有环境变量都以 ONE_MCP_ 为前缀，并覆盖配置文件和 CLI 设置：

ONE_MCP_TRANSPORT
ONE_MCP_CONFIG
ONE_MCP_CONFIG_DIR
ONE_MCP_PORT
ONE_MCP_HOST
ONE_MCP_EXTERNAL_URL
ONE_MCP_TRUST_PROXY
ONE_MCP_TAGS（已弃用）
ONE_MCP_TAG_FILTER
ONE_MCP_PAGINATION
ONE_MCP_ENABLE_AUTH
ONE_MCP_ENABLE_SCOPE_VALIDATION
ONE_MCP_ENABLE_ENHANCED_SECURITY
ONE_MCP_SESSION_TTL
ONE_MCP_SESSION_STORAGE_PATH
ONE_MCP_RATE_LIMIT_WINDOW
ONE_MCP_RATE_LIMIT_MAX
ONE_MCP_ENABLE_ASYNC_LOADING
ONE_MCP_ENABLE_CONFIG_RELOAD
ONE_MCP_CONFIG_RELOAD_DEBOUNCE
ONE_MCP_ENABLE_ENV_SUBSTITUTION
ONE_MCP_ENABLE_SESSION_PERSISTENCE
ONE_MCP_SESSION_PERSIST_REQUESTS
ONE_MCP_SESSION_PERSIST_INTERVAL
ONE_MCP_SESSION_BACKGROUND_FLUSH
ONE_MCP_ENABLE_CLIENT_NOTIFICATIONS
ONE_MCP_HEALTH_INFO_LEVEL
ONE_MCP_LOG_LEVEL
ONE_MCP_LOG_FILE

配置示例

开发设置

bash

# 带调试日志和完整健康信息的开发
npx -y @1mcp/agent \
  --log-level debug \
  --health-info-level full \
  --enable-async-loading \
  --enable-config-reload

# 用于开发的环境变量
ONE_MCP_LOG_LEVEL=debug \
ONE_MCP_HEALTH_INFO_LEVEL=full \
ONE_MCP_ENABLE_ASYNC_LOADING=true \
ONE_MCP_ENABLE_CONFIG_RELOAD=true \
npx -y @1mcp/agent

生产部署

bash

# 带身份验证的生产 HTTP 服务器
npx -y @1mcp/agent \
  --host 0.0.0.0 \
  --port 3051 \
  --enable-auth \
  --enable-enhanced-security \
  --trust-proxy true \
  --external-url https://mcp.yourdomain.com \
  --enable-session-persistence \
  --session-persist-requests 200 \
  --session-persist-interval 10

# Docker 环境变量
docker run -p 3051:3051 \
  -e ONE_MCP_HOST=0.0.0.0 \
  -e ONE_MCP_PORT=3051 \
  -e ONE_MCP_ENABLE_AUTH=true \
  -e ONE_MCP_ENABLE_ENHANCED_SECURITY=true \
  -e ONE_MCP_TRUST_PROXY=true \
  -e ONE_MCP_EXTERNAL_URL=https://mcp.yourdomain.com \
  -e ONE_MCP_ENABLE_SESSION_PERSISTENCE=true \
  -e ONE_MCP_SESSION_PERSIST_REQUESTS=200 \
  -e ONE_MCP_SESSION_PERSIST_INTERVAL=10 \
  ghcr.io/1mcp-app/agent

过滤服务器访问

bash

# 仅网络功能服务器
npx -y @1mcp/agent --transport stdio --tag-filter "network"

# 复杂过滤：（web 或 api）且 production，非 test
npx -y @1mcp/agent --transport stdio --tag-filter "(web,api)+production-test"

# 自然语言过滤
npx -y @1mcp/agent --transport stdio --tag-filter "api and database and not test"

高级功能配置

bash

# 启用所有高级功能并支持环境替换的完整配置
API_KEY="${API_KEY}" \
DB_CONNECTION="${DATABASE_URL}" \
npx -y @1mcp/agent \
  --enable-config-reload \
  --config-reload-debounce 1000 \
  --enable-env-substitution \
  --enable-session-persistence \
  --session-persist-requests 150 \
  --session-persist-interval 8 \
  --enable-client-notifications \
  --log-level info

# 仅配置重载（禁用其他新功能以确保稳定性）
npx -y @1mcp/agent \
  --enable-config-reload \
  --config-reload-debounce 2000 \
  --enable-env-substitution false \
  --enable-session-persistence false \
  --enable-client-notifications false

# 高性能环境的最小配置
npx -y @1mcp/agent \
  --enable-config-reload false \
  --enable-env-substitution true \
  --enable-session-persistence false \
  --enable-client-notifications false \
  --log-level warn

另请参阅

MCP 服务器参考 - 后端服务器配置
Serve 命令参考 - 命令行使用示例
信任代理指南 - 反向代理配置
健康检查参考 - 监控和健康端点
安全指南 - 安全最佳实践

配置深入指南 ​

配置方法 ​

命令行选项 ​

配置类别 ​

传输选项 ​

网络配置 ​

配置管理 ​

安全配置 ​

网络安全 ​

服务器过滤 ​

性能选项 ​

配置重载 ​

环境变量替换 ​

会话持久化 ​

客户端通知 ​

监控和健康 ​

日志配置 ​

环境变量参考 ​

配置示例 ​

开发设置 ​

生产部署 ​

过滤服务器访问 ​

高级功能配置 ​

另请参阅 ​

配置深入指南

配置方法

命令行选项

配置类别

传输选项

网络配置

配置管理

安全配置

网络安全

服务器过滤

性能选项

配置重载

环境变量替换

会话持久化

客户端通知

监控和健康

日志配置

环境变量参考

配置示例

开发设置

生产部署

过滤服务器访问

高级功能配置

另请参阅