---
date: 2026-05-18
tags: [internal-app-platform, mcp, claude-code, bug-found]
severity: high
status: fixed-in-branch
---

# FFOA 接入页颁发的 `/mcp add` 命令格式不正确，员工跑了报 "No MCP servers configured"

## 现象

[`token.service.ts:126`](../backend/src/modules/internal-app-platform/services/token.service.ts) 生成给员工复制的命令：

```
/mcp add ffoa-apps <URL> --header "Authorization: Bearer ffoa_xxx"
```

员工在 Claude Code CLI 终端粘贴这一行，期望注册 MCP。**实际**：CLI 返回

```
No MCP servers configured. Please run /doctor if this is unexpected.
Otherwise, run claude mcp --help or visit https://code.claude.com/docs/en/mcp
```

跟"没注册成功"等价。

## 根因

两个 bug 叠加：

1. **入口错了**：Claude Code CLI 没有 `/mcp add <name> <url> --header ...` 这种 slash 命令形式。`/mcp` slash 在 CLI 内会打开交互菜单/列表，不接受这种命令行参数。**正确入口是 shell 子命令** `claude mcp add ...`（在 shell 终端跑，不是在 Claude Code 会话内）。
2. **缺 `--transport http`**：`claude mcp add` 默认假设是 **stdio** 子进程命令；HTTP MCP 必须显式声明 `--transport http`，否则 CLI 会把 URL 当成一个本地命令尝试执行。

## 正确的命令

```bash
claude mcp add --transport http ffoa-apps \
  https://ffworkspace.test.faradayfuturecn.com/api/v1/internal-apps/mcp \
  --header "Authorization: Bearer ffoa_xxx"
```

`claude mcp --help` 的官方示例（已验证）：

```
# Add HTTP server with headers:
claude mcp add --transport http corridor https://app.corridor.dev/api/mcp --header "Authorization: Bearer ..."
```

## 修复（分支 `fix/mcp-add-command-format` → develop）

- [`backend/src/modules/internal-app-platform/services/token.service.ts:126`](../backend/src/modules/internal-app-platform/services/token.service.ts) — 改成 `claude mcp add --transport http ...`
- [`frontend/src/locales/internalApps/zh.ts`](../frontend/src/locales/internalApps/zh.ts) + `en.ts` — `instructionHint` 文案改成"在 shell 终端（不是 Claude Code 内）执行"+ 用 `claude mcp list` 验证
- [`docs/modules/internal-app-platform/08-phase-0-poc-runbook.md`](../docs/modules/internal-app-platform/08-phase-0-poc-runbook.md) §1.4 IT 邮件模板 + §2.2 员工操作步骤都改了，加了易踩警示

## 怎么测出来的

PoC 阶段员工反复翻车 3 次，每次都是不同 Claude 环境问题。第三次终于把员工切到正确的 Claude Code CLI 上，结果命令本身格式也是错的——直接撞到这个 bug。**说明这个 bug 之前没被任何人验证过**（包括我，docs 里就是按这个格式写的）。

## 防御建议

- **测试缺口**：`token.service.ts` 的集成测试只验 `mcpAddCommand` 包含 token 和 URL，没验 CLI 真能接受这个格式。下次写 token 相关测试时，至少要硬编码一份"已知好"的命令模板对照。
- **每次改 `mcpAddCommand` 必须找一台真机粘进 Claude Code CLI 验证**，不能光跑单测/集成测试就放过。
- 把"找真机粘 CLI 验证"列入 `09-test-scenarios.md` 的 L3（人工验收）必选项。

## 适用范围

- 任何写 MCP 接入命令的项目：不要凭印象写 `/mcp add ...`，先 `claude mcp --help` 看一遍当前 CLI 实际支持的语法
- HTTP MCP 一定要显式 `--transport http`，stdio MCP 一定不能加