# MCP

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

## 快速上手

```bash
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>`）。

全部子命令：

```bash
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` 前绑定到进程：

```bash
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`）。格式：

```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 工具暴露给模型（见[内置工具](tools.zh.md)的 `mcp_meta`）。