配置深入指南

Name: 1MCP Agent
Author: 1MCP

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

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

两个配置文件

请将后端清单与 1MCP 运行时设置分到不同文件中。它们会从同一配置目录加载，但使用不同的 schema。

mcp.json 包含 mcpServers，即后端 MCP 清单。服务器使用 type（stdio、http、sse 或 streamableHttp），需要暂时不启动时使用 disabled。
config.toml 包含身份验证、异步加载、日志和运行时默认值等应用设置；其中不包含 mcpServers。

json

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "tags": ["files"]
    },
    "remote-api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "disabled": false
    }
  }
}

toml

# config.toml
[auth]
enabled = true

[asyncLoading]
enabled = true
batchNotifications = true
batchDelay = 250

CLI 参数及其 ONE_MCP_* 环境变量等价项会覆盖当前进程的这些运行时设置。不要把 [auth] 或 [asyncLoading] 写进 mcp.json，也不要把 mcpServers 写进 config.toml。

配置方法

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

命令行标志：显式提供时优先级最高
环境变量：为进程提供 ONE_MCP_* 默认值
配置文件：基础配置（在 MCP 服务器参考中介绍）

命令行选项

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

选项 (CLI)	环境变量	描述	默认值
`--transport`, `-t`	`ONE_MCP_TRANSPORT`	选择传输类型（"stdio"、"http" 或 "sse"）	"http"
`--config`, `-c`	`ONE_MCP_CONFIG`	使用特定的配置文件
`--config-dir`, `-d`	`ONE_MCP_CONFIG_DIR`	配置目录路径（覆盖默认配置位置）
`--cli-session-cache-path`	`ONE_MCP_CLI_SESSION_CACHE_PATH`	`run` / `inspect` CLI 会话缓存路径模板，支持 `{pid}` 与 `{scope}`
`--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"
`--filter`, `-f`	`ONE_MCP_FILTER`	按简单逗号分隔标签或高级布尔逻辑筛选运行时暴露的服务器
`--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
`--async-max-concurrent-loads`	`ONE_MCP_ASYNC_MAX_CONCURRENT_LOADS`	最大并发后端加载数	5
`--async-max-retries`	`ONE_MCP_ASYNC_MAX_RETRIES`	首次尝试后的前台重试次数	3
`--async-retry-delay`	`ONE_MCP_ASYNC_RETRY_DELAY`	指数退避初始延迟（毫秒）	2000
`--async-background-retry`	`ONE_MCP_ASYNC_BACKGROUND_RETRY`	为可重试的后端失败启用周期性重试	true
`--async-background-retry-interval`	`ONE_MCP_ASYNC_BACKGROUND_RETRY_INTERVAL`	后台重试间隔（毫秒）	60000
`--async-background-retry-max-servers`	`ONE_MCP_ASYNC_BACKGROUND_RETRY_MAX_SERVERS`	每轮最多选择的失败后端数	3
`--enable-lazy-loading`	`ONE_MCP_ENABLE_LAZY_LOADING`	启用元工具暴露以逐步发现工具（布尔值）	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
`--enable-internal-tools`	`ONE_MCP_ENABLE_INTERNAL_TOOLS`	为 AI 助手启用所有 MCP 内部工具（布尔值）	false
`--internal-tools`	`ONE_MCP_INTERNAL_TOOLS`	启用特定的内部工具类别（discovery,installation,management,safe）
`--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

示例：

CLI 会话缓存路径

run 和 inspect 默认会在配置目录之外维护一个轻量级会话缓存文件。

默认值：${os.tmpdir()}/1mcp/.cli-session.{pid}.{scope}
环境变量：ONE_MCP_CLI_SESSION_CACHE_PATH
占位符：{pid} 在可用时会解析为发现到的 1mcp serve 进程 PID；{scope} 用于隔离目标 URL 与 CLI 上下文。对于内置默认路径，如果无法得到 PID，1MCP 会退回到稳定的服务器标识。

示例：

bash

ONE_MCP_CLI_SESSION_CACHE_PATH=/tmp/1mcp/.cli-session.{pid}.{scope} npx -y @1mcp/agent run filesystem/read_file --args '{"path":"./README.md"}'

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

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

如果需要推荐的 Caddy 公开 HTTPS、Admin Console 和本地 CLI Runtime Target 路径，请参阅 使用 Caddy 进行云端部署。

上游 OAuth 授权主体

HTTP 和 SSE 上游在两代协议中遵循相同的 OAuth 授权主体规则。通过服务器的 oauth 对象配置客户端注册和 issuer 选择：

json

{
  "mcpServers": {
    "reports": {
      "type": "http",
      "url": "https://reports.example/mcp",
      "oauth": {
        "issuer": "https://login.example",
        "clientId": "registered-client-id",
        "redirectUrl": "https://gateway.example/oauth/callback/reports",
        "scopes": ["reports.read"]
      }
    }
  }
}

issuer 必须与获准的签发者标识完全一致，包括末尾斜杠。未显式指定时，会选择与当前配置兼容的已获准 issuer，或上游声明的唯一 issuer；如果列表中存在多个候选项，必须配置 issuer。配置的 clientId/clientSecret 优先于已持久化的动态注册信息。如果未配置客户端，clientMetadataUrl 可启用上游声明支持的 HTTPS 客户端 ID 元数据文档（CIMD），其次才是上游声明支持的动态客户端注册（DCR）。autoRegister: false 禁用 DCR。只有旧版上游适配器允许在缺少授权服务器元数据时推导同源注册端点。身份验证失败不会触发协议代际降级。

凭据绑定到 Runtime Scope、配置来源、结构化上游目标、精确的 issuer 和资源，以及与安全相关的配置。更改这些信息后必须重新授权。模板实例之间保持隔离，除非有意使用相同的 oauth.credentialAuthority；共享凭据还要求目标、注册配置、权限范围和已注册的重定向 URI 完全一致。此设置不会授予入站客户端使用上游的权限：现有的逐操作授权检查仍然适用。

每次授权尝试都有独立的 state 和 PKCE verifier，十五分钟后过期，可在重启后继续，但只能消费一次。在该时间窗口内，每个授权主体最多保留 32 条尝试记录。回调过期、被拒绝或中断后，应重新发起授权。旧版按服务器名称索引的凭据会被隔离到仅所有者可访问的客户端存储中，不会自动迁移为已绑定凭据；升级后需要重新授权。隔离数据仍是受保护的回滚材料，不包含在配置导出中。恢复这些数据也不会使未绑定凭据变为可用。

OAuth 元数据、注册和令牌响应的大小上限为 1 MiB，总耗时上限为十秒。OAuth 请求不接受重定向。如果配置的 MCP 资源发生重定向（例如从 /mcp 跳转到 /mcp/），1MCP 会提示将上游 URL 配置为最终目标，不会通过重定向转发凭据。通过发现获得的端点默认必须使用公网 HTTPS。显式配置的本地 IP 或 localhost 资源/issuer 源允许 HTTP 和私有网络访问；oauth.privateNetworkOrigins 则单独允许所列 HTTPS 源访问私有地址。独立的本地授权服务器必须通过 oauth.issuer 显式指定；上游声明另一个 localhost 端口或地址并不代表该目标已获准访问。精确配置的 MCP 资源路由，以及已接受的同源 SSE 消息端点，保留运维配置允许的 HTTP/私有网络访问能力；这不会批准通过发现获得的 OAuth 端点。服务器发起网络请求时，会验证每次 DNS 解析结果，并将其固定到该请求的实际连接。通过验证的地址可以在不同请求之间轮换。活跃的授权主体和凭据记录会续期其三十天的存储有效期；闲置过期的记录仍需重新授权。发送凭据前会验证端点 URL 和权限范围。资源指示符（Resource Indicator）可以指向同源父路径（例如 /api/mcp 对应的 /api），但查询参数必须一致，且不能包含片段。所选资源指示符作为令牌的受众保留；凭据仍绑定到精确配置的上游路由。上游资源请求的请求头不会转发到发现、注册或令牌端点。MCP SSE 流保持正常的流式连接生命周期。浏览器授权跳转使用经过验证的精确 HTTPS URL（显式配置的本地 origin 除外）；浏览器自行控制 DNS 和网络连接，1MCP 不会固定浏览器的连接地址。

访问令牌可以是不透明令牌。1MCP 将令牌交换和资源指示符绑定到经过验证的授权主体，不会解码任意令牌声明并声称已验证其签名。受保护资源仍负责访问令牌的密码学验证。

显式启用不安全的元数据兼容模式

优先修复提供方的元数据。如果无法修复，可为该服务器设置 oauth.insecureAllowIncompleteMetadata: true。此选项不安全且默认关闭，对公网和私有网络提供方均适用。它根据授权服务器发现上下文补齐缺失的 issuer，并以该 issuer 为基准解析授权、令牌、注册和 JWKS 端点的相对 URL。受保护资源元数据不可用时，它还允许在已配置资源的同源地址发现授权服务器。它不会替换显式但不匹配的 issuer、猜测缺失的必需端点、接受跨源相对 URL，也不会关闭资源、重定向、TLS 或凭据校验。

DNS 解析到私有地址需要单独批准。将 oauth.privateNetworkOrigins 设置为明确可信的 HTTPS 源（协议、主机和可选端口；不得包含凭据、通配符、路径、查询参数或片段）。允许末尾斜杠。这不会允许私有主机名使用 HTTP，也不会批准发现文档中声明的其他主机名或端口。避免将任一例外配置放入 serverDefaults.oauth，因为没有独立 OAuth 对象的服务器会继承它。

json

{
  "mcpServers": {
    "home-assistant": {
      "type": "http",
      "url": "https://ha.example/api/mcp",
      "oauth": {
        "insecureAllowIncompleteMetadata": true,
        "privateNetworkOrigins": ["https://ha.example"],
        "clientId": "http://127.0.0.1:3050/",
        "redirectUrl": "http://127.0.0.1:3050/oauth/callback/home-assistant",
        "autoRegister": false
      }
    }
  }
}

Home Assistant 示例使用其支持的 URL 客户端标识，并保持回调同源，因为它不支持动态客户端注册。如果本地 1MCP 的端口或源不同，请同时调整客户端 ID 和回调地址。其他提供方可能要求预先注册的客户端 ID 或已发布的 clientMetadataUrl；仅关闭自动注册不会提供客户端标识。

公网目标无需配置 privateNetworkOrigins；元数据完整时无需配置 insecureAllowIncompleteMetadata。修改任一设置后需要重新授权。这些选项不保证提供方授权成功。

private_destination_blocked 表示 DNS 解析到了未经批准的私有地址；invalid_metadata 表示提供方文档未通过格式校验；authority_mismatch 表示授权主体校验失败。

OAuth 原生凭据存储

文件存储仍为默认值，并保留仅所有者可访问的文件/目录、权限检查和符号链接防护。要将入站和上游 OAuth 安全记录放入系统凭据库，请在 config.toml 中设置以下内容，然后重启对应的 Runtime Scope：

toml

[auth]
credentialStore = "native"

--credential-store native 或 ONE_MCP_CREDENTIAL_STORE=native 会覆盖当前进程的文件设置。此选项作用于整个 Runtime Scope，并在启动时捕获；修改设置不会切换正在运行的实例。同一策略保护入站与上游 OAuth。auth.enabled 仅控制连接到 1MCP 的客户端是否必须认证，不会关闭上游凭据保护。Admin 凭据和会话继续使用文件存储，授权身份独立。

将对应平台的 Docker credential helper 安装到运行时可信的可执行文件搜索路径：

平台	必需 helper	前提
macOS	`docker-credential-osxkeychain`	可访问且已解锁的 Keychain
Windows	`docker-credential-wincred.exe`	运行账号能够访问 Credential Manager
Linux	`docker-credential-secretservice`	用户 D-Bus 会话，以及已解锁的 Secret Service 集合，例如 GNOME Keyring

无需安装 Docker 本身。npm 和独立二进制均需要这些外部 helper，1MCP 不会自动安装。无桌面服务和容器需要显式提供可访问的 Secret Service 会话。helper 缺失、凭据库锁定、访问被拒绝、响应格式错误或持久化失败时，受影响的 OAuth 操作会安全拒绝，并给出可操作且不含秘密的错误。不会绕过入站认证，也不会根据不确定的状态签发令牌。不会自动回退到明文；独立的 Admin 访问和无关后端仍可使用。进程正在运行不代表受影响的凭据域已就绪或迁移已完成。

native 模式启动时自动保护符合条件的现有入站和上游记录。入站记录包括访问令牌会话、授权码、待确认授权请求、客户端注册及其秘密、刷新令牌族和摘要查询记录。保护覆盖完整记录及受管理的临时/恢复副本，包括扩展字段中的秘密；入站刷新令牌仍只持久化摘要。有效会话和注册保留有效期、客户端/资源/权限绑定、授权确认状态、授权码单次使用、刷新令牌族继承关系和撤销状态。上游保护包括令牌和注册数据、待完成授权的 PKCE，以及受管理的旧凭据隔离/回滚记录。只有验证原生存储目标后才清理明文来源。中断的迁移或未完成的明文清理会保留恢复引用并报告未完成；解锁凭据库并重启后可继续。格式损坏的权威数据会保留用于恢复，并阻止受影响操作；旧残留不会作为备用凭据或覆盖较新状态。未绑定的旧凭据仍需重新授权，移动它们不会建立授权身份。存储身份保留 Runtime Scope、凭据域、入站身份与配置的上游授权主体隔离。不同 Runtime Scope 不能共享同一上游凭据目录；启动时会拒绝此配置。

早期原生存储版本仅保护上游 OAuth。已配置为 native 的 Runtime Scope 升级后，会在启动时自动将同一策略扩展到入站 OAuth；升级前请满足相同的 helper 和凭据库条件。没有单独的入站开关，也不会自动降级。

切回 file 需要重启，除非已显式导出记录，否则入站和上游均需重新授权，不会静默导出原生秘密，也不会复用迁移残留。要有意执行反向迁移，先停止运行时，再使用 auth export-oauth-credentials，导出入站与上游两个 OAuth 域，排除 Admin 记录。auth export-upstream-credentials 仅导出上游记录。它会先显示所有明文目标（包括当前和旧布局），再要求交互确认或显式非交互确认。重复导出会保护较新的凭据，并报告未完成的清理。

成功迁移会删除受管理的明文副本及恢复残留，但不会安全擦除历史备份、外部副本、文件系统快照或已删除的磁盘块；这些需要单独保护和处理。系统凭据库改善静态存储，但不能全面防御以相同系统用户身份运行的任意代码。

服务器过滤

控制运行时暴露哪些后端 MCP 服务器。

--filter, -f <expression>

用途：使用简单 OR 语法或高级布尔逻辑筛选运行时暴露面
环境变量：ONE_MCP_FILTER

过滤语法：

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

示例：

bash

# 简单 OR 过滤
npx -y @1mcp/agent --filter "network,filesystem"

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

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

如果运行时已经启动，而你只想对客户端侧做进一步收窄，请优先在 instructions、inspect、run 上使用 --preset 与 --filter，或在最大兼容性的 stdio 路径上使用 proxy --preset/--filter。--tags 与 --tag-filter 仍可作为兼容旧用法的别名使用，但应优先采用统一的 --filter 与 ONE_MCP_FILTER。

内部工具选项

控制为 AI 助手暴露的 MCP 内部工具。

--enable-internal-tools

用途：为 AI 助手启用所有 MCP 内部工具
默认值：false
环境变量：ONE_MCP_ENABLE_INTERNAL_TOOLS

--internal-tools <类别>

用途：启用特定的内部工具类别
值：逗号分隔的类别：discovery,installation,management,safe
默认值：未启用任何类别
环境变量：ONE_MCP_INTERNAL_TOOLS

类别说明：

discovery - 用于发现 MCP 服务器的工具（mcpsearch, mcp_registry*）
installation - 用于安装/更新/移除服务器的工具（mcp_install, mcp_update, mcp_uninstall）
management - 用于管理服务器生命周期的工具（mcp_enable, mcp_disable, mcp_list, mcp_status, mcp_reload, mcp_edit）
safe - 仅限只读工具（discovery 和 management 的子集）

示例：

bash

# 启用所有内部工具
npx -y @1mcp/agent --enable-internal-tools

# 仅启用发现和管理工具
npx -y @1mcp/agent --internal-tools "discovery,management"

# 仅启用安全（只读）工具
npx -y @1mcp/agent --internal-tools "safe"

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

ONE_MCP_INTERNAL_TOOLS="discovery,management" npx -y @1mcp/agent

重要提示：内部工具与 CLI 命令不同。CLI 命令是为人类用户设计的，而内部工具是 MCP 协议工具，AI 助手可以用来自动化服务器管理任务。有关可用内部工具的详细信息，请参阅**内部工具参考**。

性能选项

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

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

启动时捕获的运行策略

以下设置会在聚合运行时启动时完成校验并捕获。修改 config.toml 不会实时替换限流器、重试定时器、加载并发、日志保留策略或模板实例池限制；必须重启对应 Runtime Scope 才会生效。

toml

[asyncLoading]
maxConcurrentLoads = 5
maxRetries = 3
retryDelay = 2000

[asyncLoading.backgroundRetry]
enabled = true
interval = 60000
maxServersPerCycle = 3

[admin.rateLimit.login]
windowSeconds = 900
maxRequests = 30
maxFailedAttempts = 5

[admin.rateLimit.status]
windowSeconds = 60
maxRequests = 120

[admin.rateLimit.sensitive]
windowSeconds = 900
maxRequests = 10

[health.rateLimit]
windowSeconds = 300
maxRequests = 200

[admin.audit]
retentionDays = 30

[templateSettings.pool]
maxInstancesPerTemplate = 50
maxTotalInstances = 100
idleTimeout = 300000
cleanupInterval = 30000

异步加载的 CLI 值覆盖对应的 ONE_MCP_* 值，环境变量再覆盖 config.toml。maxRetries = 0 表示只执行首次尝试；retryDelay = 0 会取消等待，但重试次数仍然有限。后台间隔至少为 1000 毫秒。后端的 connectionTimeout、旧版后端 timeout、最后 30000 毫秒回退值依次决定唯一的连接尝试截止时间。已弃用的 asyncLoading.minServers 与 asyncLoading.timeout 仍只是产生警告的无操作配置。

Admin 与健康检查限流不能关闭。窗口范围为 1-86400 秒，请求上限为 1-100000，登录失败阈值为 1-100，审计保留期为 1-3650 天。这些进程内控制与 OAuth --rate-limit-* 配置相互独立。审计保留期只影响脱敏后的审计事实；已完成/失败操作的幂等回放固定为 24 小时，结果不明确的 state_unknown 固定保留 30 天。

模板池的时间值使用毫秒。maxInstancesPerTemplate 范围为 0-10000，零表示在全局有限上限内不限制单模板实例数；maxTotalInstances 范围为 1-10000；idleTimeout 范围为 0-2147483647，零表示立即具备清理资格；cleanupInterval 范围为 1000-3600000。每个模板的 template.maxInstances 与 template.idleTimeout 只覆盖各自的回退值。

懒加载

懒加载是一种可选的稳定工具表面兼容模式，适用于支持逐步发现工具的客户端。默认关闭时，1MCP 会直接暴露全部后端工具；启用后，后端工具表面为 tool_list、tool_schema 和 tool_invoke，客户端通过这些元工具发现 Schema 并调用后端工具。由运维人员显式启用的内部管理工具仍会以 1mcp 命名空间直接暴露。

它可以减少初始工具 Schema 的负载，但不会减少后端连接或进程、让同步启动更早绑定端口，也不会修复遗留的代理进程。不要默认将它与异步加载同时启用；应根据各自的运行时行为分别选择。异步能力发布后，符合条件的后就绪服务器无需重连即可在下一次请求中可见；该请求时可见性契约见 #392。

仅为本次启动启用：

bash

1mcp serve --enable-lazy-loading

也可以在 config.toml 中持久启用，并重启进程：

toml

[lazyLoading]
enabled = true

CLI 参数优先于 config.toml。旧的 --lazy-mode、[lazyLoading].mode 和 --lazy-direct-expose 输入会在一个兼容周期内继续接受，但将被忽略并产生弃用警告；enabled 是唯一有效的开关。

模板上下文信任

模板上下文能够控制可执行字段，因此运行时会独立于传输连接和 OAuth 对其进行验证。默认采用本地优先的验证模式：

toml

[templateContext]
trust = "verified"

对应的 CLI 参数是 --template-context-trust verified；CLI 输入优先于 config.toml。

模式	行为
`verified`	只有带 Runtime Scope 证明的第一方本地上下文可以渲染模板；未签名客户端只能使用静态服务器。
`disabled`	请求上下文永远不能渲染模板。
`legacy`	未签名的本地或远程上下文可以渲染模板，并重新开放对模板 `command`、`args`、`cwd` 和 `env` 的控制。

在非回环 HTTP 地址上使用 legacy 时，还必须提供 --confirm-untrusted-template-context。GET REST 客户端继续使用现有的 base64url context 查询格式。运行时会将其解码为结构化、已脱敏的审计日志，通用请求日志不会打印原始 base64 值或证明签名。

配置重载

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

启用热重载后，将 mcp.json 中静态服务器的 disabled 设为 true 会保留其定义并卸载运行时连接。该服务器的工具、资源和提示词将不可用；由 1MCP 启动的 stdio 子进程会停止，独立托管的 HTTP/SSE 服务则继续运行。设回 disabled: false 会加载最新配置，无需重启 1MCP。初始禁用的服务器保持未加载状态。客户端能力变更通知遵循 --enable-client-notifications 设置。

--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} 或 $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 会话持久化以提高服务器重启时的可靠性。

启用身份验证时，未绑定授权信息的旧版 Streamable HTTP 会话需要在升级后重新初始化。重新连接时不携带 mcp-session-id，即可创建新会话。续期令牌的客户端、资源和权限范围集合与原始授权一致时，可以继续使用该会话。禁用权限范围验证后，身份验证和会话归属检查仍然生效。

--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_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 --filter "network"

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

# 自然语言过滤
npx -y @1mcp/agent --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 命令参考 - 命令行使用示例
信任代理指南 - 反向代理配置
使用 Caddy 进行云端部署 - 公开 HTTPS 部署路径
健康检查参考 - 监控和健康端点
安全指南 - 安全最佳实践

配置深入指南 ​

两个配置文件 ​

配置方法 ​

命令行选项 ​

配置类别 ​

传输选项 ​

CLI 会话缓存路径 ​

网络配置 ​

配置管理 ​

安全配置 ​

网络安全 ​

上游 OAuth 授权主体 ​

显式启用不安全的元数据兼容模式 ​

OAuth 原生凭据存储 ​

服务器过滤 ​

内部工具选项 ​

性能选项 ​

启动时捕获的运行策略 ​

懒加载 ​

模板上下文信任 ​

配置重载 ​

环境变量替换 ​

会话持久化 ​

客户端通知 ​

监控和健康 ​

日志配置 ​

环境变量参考 ​

配置示例 ​

开发设置 ​

生产部署 ​

过滤服务器访问 ​

高级功能配置 ​

另请参阅 ​

配置深入指南

两个配置文件

配置方法

命令行选项

配置类别

传输选项

CLI 会话缓存路径

网络配置

配置管理

安全配置

网络安全

上游 OAuth 授权主体

显式启用不安全的元数据兼容模式

OAuth 原生凭据存储

服务器过滤

内部工具选项

性能选项

启动时捕获的运行策略

懒加载

模板上下文信任

配置重载

环境变量替换

会话持久化

客户端通知

监控和健康

日志配置

环境变量参考

配置示例

开发设置

生产部署

过滤服务器访问

高级功能配置

另请参阅