在 assistant-ui 中接入用户自选的 MCP…

当需要在 assistant-ui 前端让用户连接预设或自定义 Streamable HTTP MCP 服务器，并把其工具纳入聊天模型上下文时使用。

适用场景

解决思路

1. 开始实现前先查看 `https://www.assistant-ui.com/llms.txt`，以获取最新 API。
2. 使用 `@assistant-ui/react-mcp`，让用户在浏览器中连接预设或自定义的 Streamable HTTP MCP 服务器；由 manager 持久化服务器与认证状态、向 primitives 暴露连接状态，并把每个已连接工具注册进 `modelContext`，注册名为 `serverId__toolName` 的 frontend tool。
3. 按需查阅参考文档：`./references/setup.md` 用于 manager 配置、存储、状态、imperative methods 和 resource reads；`./references/ui.md` 用于 copied configuration dialog 以及 manager、server、add form primitives；`./references/oauth.md` 用于 auth shapes、OAuth callback、CIMD 和 connection states。
4. 挂载 manager 时，用 `defineConnector` 声明固定 connectors，然后扩展最近的 `aui` scope 并附带 config。
5. 把 `connectionTimeout` 作为 manager 默认值，单位毫秒；connector 或 custom server 可覆盖它，用于自己的 connect 和 `listTools()` readiness flow。
6. 在客户端组件中声明 `use client` 指令，并导入 `AuiConfig`、`AuiProvider`、`useAui`、`McpManagerResource`、`defineConnector`。
7. 为每个预设 connector 调用 `defineConnector`，传入 `id`、`name`、`url`、`auth`，可选 `icon` 和 `connectionTimeout`；OAuth 用 `auth.type` 为 `oauth` 并传 `scopes`，例如 `read`；无认证用 `auth.type` 为 `none`。
8. 在 Providers 中调用 `useAui()`，构造 `AuiConfig({ mcp: McpManagerResource({ connectors, connectionTimeout: 15_000 }) })`，并用 `<AuiProvider extends={aui} config={config}>` 包裹 children。
9. Connectors 是应用预设，不能被移除；custom server 由用户通过 `McpAddFormPrimitive` 或 `aui.mcp.addCustomServer(...)` 提供；两者共享 state、storage、elicitation 和 tool registration 路径。
10. 要让 frontend tool calls 后会话继续：manager 会自动注册已连接工具，但 chat runtime 仍必须把完成的 frontend tool results 发送到 route，模型才能继续。
11. 在 `useChatRuntime` 上配置 `sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls`，并用 `AssistantRuntimeProvider` 提供 runtime。
12. 如果没有 chat runtime 提供 `modelContext`，manager 会挂载一个最小 runtime；在事件处理器中需要直接调用工具时，用 `aui.mcp.server({ id }).callTool(...)`。
13. 安装样式化配置对话框：运行 `npx assistant-ui@latest add mcp-config`。
14. `mcp-config` 是 copied runtime connected element；从 `@/components/assistant-ui/elements/mcp-config.aui` 导入 `McpConfigDialog`，并渲染在 manager provider 下。
15. 要替换默认 trigger，把一个 element 作为 `children` 传给 `McpConfigDialog`。
16. 对于 settings page、sidebar 或自定义 add flow，组合 headless primitives（`McpManagerPrimitive`、`McpServerPrimitive`、`McpAddFormPrimitive`、`McpElicitationPrimitive`），并参考 ui 文档。
17. 当 MCP server 在 tool call 进行中请求结构化输入时，渲染 elicitation；在与已连接 server 相同的 `mcpServer` scope 中渲染 `McpElicitationPrimitive.Items`。
18. 要让某个 connector 或 custom server 放弃 elicitation protocol capability，在其上设置 `elicitation: false`。
19. Elicitation UI 使用 `McpElicitationPrimitive.Items` 包裹渲染函数，再渲染 `Root`，并在 `Root` 内放 `Message`、`Error`、`Fields`、`Accept`、`Decline`、`Cancel`。
20. 在 `McpElicitationPrimitive.Fields` 的渲染函数中接收 `name`、`schema`、`value`、`setValue`，按 `schema` 渲染字段。
21. 当 `schema.type` 为 `boolean` 时渲染 checkbox，并用 `setValue(event.target.checked)` 设置 boolean。
22. 当 `schema.enum` 存在时渲染 select；若 enum 不包含空字符串，提供占位 option `Select {name}`，并用 `setValue(event.target.value)` 设置字符串。
23. 其他字段渲染 input；仅当 value 是 string 或 number 时显示 `String(value)`，否则显示空字符串；用 `setValue(event.target.value)` 更新。
24. 为 `Accept`、`Decline`、`Cancel` 分别渲染 Submit、Decline、Cancel 按钮。
25. Elicitation 渲染函数每次收到一个独立的 active request；有效数字字符串会被强制转换；boolean 字段必须设置 boolean。
26. 空字符串表示未回答，除非 property 通过 enum member 或 default 允许；所以 enum property 应渲染为 select。
27. 缺少 required fields 或值 invalid 时，`Accept` 保持 disabled。
28. 实现时只依赖 v1 已支持能力：tool listing/invocation、resource listing/reads、form elicitation、OAuth with PKCE and DCR、bearer 和 no auth、Streamable HTTP transport、manual connect/disconnect。
29. 不要把 v1 暂缓能力作为依赖：prompts、sampling、带 backoff 的 automatic reconnect、persisted per tool enablement、per tool consent、built in token encryption。
30. 排查工具从未到达模型：确认 server 处于 `connected`；其工具名为 `serverId__toolName`，不是单独的 MCP tool 名。
31. 排查工具从未到达模型：在 `useChatRuntime` 上配置 `sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls`，让完成的 frontend tool calls 恢复模型。
32. 排查 OAuth callback 失败或永远不完成：callback route 必须与 `oauthRedirectUri` 完全匹配，并在 manager provider 下渲染 `McpOAuthCallback`。
33. 排查 OAuth callback 失败或永远不完成：仅有 CIMD 且没有 registration endpoint 的 authorization server 需要静态 OAuth `clientId`。
34. 排查 server state 跨用户泄漏或 storage 切换丢记录：`McpLocalStorage()` 仅浏览器可用且明文保存 tokens；生产 auth state 应使用 HTTP-only cookie backed `McpCustomStorage`。
35. 排查 server state 跨用户泄漏或 storage 切换丢记录：不要为另一个用户切换 `storage`；custom server records 只 hydrate 一次，应 remount manager；参考 storage identity。
36. 排查 elicitation form 一直空白：`Items` 在没有 pending requests 时不会渲染，且需要匹配的 server scope；确认 server 已连接且没有设置 `elicitation: false`。
37. 排查 resource browser 在第一页后停止：把每次返回的 `nextCursor` 传给 `listResources({ cursor })`，直到 nextCursor 不存在；然后对选中项调用 `readResource(uri)`。
38. 与其他技能配合：应用自有的前后端工具用 tools 技能；CLI setup 与 `mcp` project template 用 setup 技能；`useChatRuntime` 与 runtime provider 配置用 runtime 技能；安装或修改 copied `mcp-config` element 用 elements 技能。

适用边界 · 注意事项

• 不适用于应用自有的后端 MCP 工具；这类应使用 tools 技能。
• 不适用于需要 prompts、sampling、自动重连与退避、按工具持久启用、按工具同意或内置 token 加密等 v1 未支持能力的场景。
• 若只是配置聊天运行时或修改复制出的 mcp-config dialog，应分别使用 runtime/elements 技能。