Code Puppy MCP服务器管理完全指南：/mcp命令速查与OAuth浏览器授权流程

Code Puppy 是一个面向 AI 编程的开源工具，内置完整的MCP（Model Context Protocol）服务器管理体系。你只需用/mcp命令，就能完成搜索、安装、启动、停止、日志查看等全部操作；连接需要登录的 HTTP MCP 服务器时，还能通过OAuth 浏览器授权一键完成认证，无需手动配置密钥。本文将带你快速掌握/mcp命令速查表和 OAuth 授权的完整流程。

一、MCP 服务器管理：为什么每个 AI 编程工具都需要它？

MCP 是一种让 AI 连接外部工具（数据库、文件系统、浏览器等）的标准协议。Code Puppy 把 MCP 管理做成了一个内置的「应用商店 + 控制台」组合：

• 应用商店：内置 30+ 预配置服务器目录，search+install两步即可安装；
• 控制台：启动、停止、重启、查状态、看日志，全部一条命令搞定。

核心路由逻辑位于 handler.py，所有子命令都注册在这个入口中，每个子命令独立成模块，便于维护。

二、/mcp 命令速查表：17 个子命令一次看懂

输入/mcp help即可在终端内查看全部帮助（帮助文案由 help_command.py 生成）。以下是完整的命令速查：

1. 注册表命令（找服务器、装服务器）

2. 核心生命周期命令（启动与停止）

3. 管理与排障命令（查状态、看日志、改配置）

4. 一眼看懂状态图标

✓ Running ✗ Stopped ⚠ Error ⏸ Quarantined ⭐ Popular

• ✓ Running：运行中
• ✗ Stopped：已停止
• ⚠ Error：出错（建议配合/mcp logs排查）
• ⏸ Quarantined：被隔离（连续启动失败后的保护机制）
• ⭐ Popular：注册表中的热门服务器

三、3 步安装一个 MCP 服务器：search → install → 绑定 Agent

以安装 PostgreSQL 服务器为例：

/mcp search database # 第 1 步：按关键词搜索 /mcp install postgres # 第 2 步：按 ID 直接安装 /mcp start postgres # 第 3 步：启动并使用

几个新手友好的小细节（来自 install_command.py 的实现）：

• 模糊匹配：install时既可输入精确 ID，也可以输入名称模糊搜索；匹配到多个结果时，会列出前 5 个供你选择。
• 环境变量提示：如果服务器需要环境变量（如 API Key），安装向导会逐项询问；已经设置过的变量会自动标记为"已设置"并直接沿用。
• 重名保护：目标名称已存在时会先征求确认，避免误覆盖。

安装完成后会弹出Agent 选择菜单：按空格键（Space）切换绑定哪个 Agent 可以使用该服务器，A切换自动启动（auto-start），Enter完成。跳过菜单则服务器处于"已安装但未绑定"状态，之后可以随时用/agents命令中的 MCP 绑定菜单调整。

四、OAuth 浏览器授权流程：连接需要登录的 HTTP MCP 服务器

很多 HTTP 类型的 MCP 服务器（如企业内部服务）需要账号登录。Code Puppy 支持标准OAuth + PKCE流程，全程自动发现、自动跳转浏览器，你只需在浏览器里点一次"允许"。完整说明见官方文档 MCP_OAUTH.md，底层实现位于 http_auth.py。

1. 配置方式：只需 4 个字段

在/mcp的自定义服务器添加/编辑表单中，填入如下 JSON 配置：

{ "type": "http", "url": "https://your-server.example/mcp", "auth": "oauth", "timeout": 330 }

2. 授权流程是怎么走的？

1. 正常启动服务器，客户端自动完成OAuth 发现（服务端能力探测）与PKCE参数生成；
2. 系统自动打开你的浏览器，跳转到登录页；
3. 在浏览器中完成登录并批准服务器请求的权限；
4. 本地loopback 回调监听器（127.0.0.1）接收回调结果，校验 state 后自动完成握手；
5. 连接建立，令牌在连接生命周期内自动刷新。

3. 新手必知的 4 个注意事项

另外，端点必须支持 MCP OAuth 流程及动态客户端注册；已有短超时的服务器启用 OAuth 前，建议先把timeout调大。

五、停止与绑定：控制服务器生命周期的进阶技巧

• 解绑 ≠ 停止：在 Agent 菜单中解除绑定只会让该 Agent 不再使用服务器（并取消它的缓存工具），共享的已运行连接不会因此停止；要全局停止请用/mcp stop <name>。
• 显式停止抑制自动重启：/mcp stop后，在当前会话内该服务器不会再被自动拉起，直到你再次执行/mcp start <name>。
• 停止会打断授权等待：stop会取消尚未完成的启动流程，包括浏览器授权等待中的状态。
• enabled: false的作用：保存enabled: false会阻止自动启动，但显式/mcp start <name>仍可在本会话强制启用。

六、常见问题速查：服务器起不来怎么办？

配置文件存储于 mcp_servers_store.py，交互式配置向导见 config_wizard.py。

写在最后

Code Puppy 的/mcp体系把「找服务器 → 装服务器 → 授权 → 绑定 Agent → 排障」串成了一条顺滑的工作流：日常操作记住search / install / start / stop / status / logs这 6 个高频命令就够用了；遇到需要登录的 HTTP 服务时，填上"auth": "oauth"然后放心点浏览器里的"允许"即可。现在打开 Code Puppy，输入/mcp help试试吧！