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

【免费下载链接】code_puppy

Agentic AI for writing code

项目地址：https://gitcode.com/gh_mirrors/co/code_puppy

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. 注册表命令（找服务器、装服务器）

命令	作用
`/mcp search [query]`	在 30+ 预配置服务器中按关键词搜索
`/mcp install <id>`	从注册表安装服务器（不带参数则打开交互式菜单）

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

命令	作用
`/mcp`	直接输入即列出所有已注册服务器
`/mcp start <name>`	启动指定服务器
`/mcp start-all`	一键启动全部服务器
`/mcp stop <name>`	停止指定服务器
`/mcp stop-all`	停止所有运行中的服务器
`/mcp restart <name>`	重启指定服务器

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

命令	作用
`/mcp status [name]`	查看所有或指定服务器的详细状态
`/mcp logs <name> [limit]`	查看最近事件，默认显示 10 条
`/mcp edit <name>`	编辑已有服务器的配置
`/mcp remove <name>`	移除或禁用一个服务器
`/mcp trust [accept\\|revoke\\|status]`	信任当前仓库的`.code_puppy/mcp_servers.json`
`/mcp silence-warning`	永久关闭"已注册但未绑定"的提示
`/mcp unsilence-warning`	恢复该提示

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. 授权流程是怎么走的？

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

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

注意点	说明
⏱ 预留登录时间	未显式配置`timeout`时，OAuth 连接默认使用330 秒初始化超时，足够从容完成浏览器登录
🔒 必须 HTTPS	仅本地回环（`localhost`/`127.0.0.1`）允许 HTTP
🚫 不要混用	`auth: "oauth"`不要与`Authorization`请求头同时使用；其他自定义请求头仍受支持
💾 令牌不落盘	Token 只保存在内存中，不会写入 MCP 配置文件；重启 Code Puppy 后可能需要重新登录

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

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

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

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

症状	排查命令
状态显示 ⚠ Error	`/mcp logs <name>`查看最近事件
启动缓慢	`/mcp status`查看初始化进度
仓库自带配置不被加载	`/mcp trust status`查看信任状态，用`/mcp trust accept`授权
配置填错了	`/mcp edit <name>`重新编辑
彻底不用了	`/mcp remove <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试试吧！