OpenProgram Docs

MCP#

接入任意 MCP（Model Context Protocol）server，它的工具会以 <name>__<tool> 的形式出现在聊天里供模型调用。这一页讲怎么加 server、配置存在哪、支持哪些传输方式。

快速上手#

openprogram mcp add drawio npx -y @drawio/mcp     # 加一个 stdio server，立即生效
openprogram mcp list                              # 每个已配置 server 的状态
openprogram mcp show drawio                       # 该 server 的工具与完整 schema

mcp add 的选项：--env KEY=VALUE（注入子进程环境变量，可重复）、--timeout（启动与单次调用超时秒数）、--disabled（只写配置不启动）。name 会用作该 server 所有工具的前缀（<name>__<tool>）。

全部子命令：

openprogram mcp token create       # 为本地 stdio MCP server 创建 token
openprogram mcp serve              # 通过 stdio 提供认证后的 MCP server
openprogram mcp list | show | add | rm | restart | enable | disable | edit | test

token create 只把新建的 token 原样打印为一行，不会设置当前 shell 的环境变量。 只运行一次，复制这一行，在启动 serve 前绑定到进程：

openprogram mcp token create
export OPENPROGRAM_MCP_TOKEN="<把上一步打印的 token 粘贴到这里>"
openprogram mcp serve

如果 token 已经存在，请使用此前保存的 token，不要再次运行 token create。 serve 在缺少或不匹配 OPENPROGRAM_MCP_TOKEN 时会拒绝认证。

  • rm 停止并删除配置；enable / disable 切换（disable 保留配置）。
  • edit 只作为兼容入口保留，会报告直接编辑配置已移除，因为它会暴露已存储的 secret。请用 add / rm 或 MCP 设置页；add 用于 stdio server。
  • test 用一份临时配置试拉起 server 并确认能返回工具列表，不写盘。

管理命令与常驻的 OpenProgram 后台 worker 通信；worker 未运行时先 openprogram worker start 启动（用 openprogram status 查看状态）。

Worker 启动时，已配置的 MCP server 在后台连接。可选 server 正在连接或等待 OAuth 时，App 和核心 API 仍可使用。该 server 就绪前，其远程工具不可用；mcp list 和 MCP 设置页显示实际状态。每个 server 保留配置的启动和调用 timeout。

配置存哪#

~/.openprogram/mcp_servers.json（使用 --profile <name> 时是 ~/.openprogram-<name>/mcp_servers.json）。格式：

{
  "servers": {
    "drawio": {
      "type": "local",
      "command": ["npx", "-y", "@drawio/mcp"],
      "env": {},
      "enabled": true,
      "timeout_seconds": 30
    },
    "linear": {
      "type": "http",
      "url": "https://mcp.linear.app/mcp",
      "auth": {"kind": "oauth", "client_name": "OpenProgram"},
      "enabled": true
    }
  }
}

传输与认证#

type 说明 用到的字段
local stdio 子进程 command、env
http Streamable HTTP url、headers、auth
sse 旧式 SSE url、headers、auth

auth.kind 支持 none / bearer（token 字段）/ oauth（OAuth 2.1 PKCE；支持动态客户端注册的 server 零配置即可，预注册客户端的 server 才需要填 client_id / client_secret）。

OAuth 只需授权一次#

OAuth server 首次连接时，OpenProgram 会在浏览器打开授权页，并用 localhost 回调接住跳转。整个流程产出的状态——access / refresh token、动态客户端注册信息、发现到的授权端点——都会持久化到 ~/.openprogram/mcp_tokens/<server>.json（权限 0600）。之后的每次连接（包括 worker 重启后）都复用存储的 token；token 过期时用 refresh token 在后台静默续期。只有 refresh token 本身被拒绝（服务端吊销或过期）时才会重新弹出浏览器，管理界面会把该 server 标记为需要重新认证。要换账号或重头来过，POST /api/mcp/servers/{name}/auth/clear 会清空存储状态并重启该 server。

除了工具，MCP 的另外两类原语——resources 和 prompts——也通过一组内置 meta 工具暴露给模型（见内置工具的 mcp_meta）。

Last updated · 2026-10-10
PreviousPluginsNextBuilt-in tools