MCP Inspector 完全指南：用 @mcp-use/inspector 调试 MCP 服务器与 MCP Apps 全流程

• 后端
• MCP 服务
• MCP Clients
• AI Agent
• 人工智能

【免费下载链接】mcp-use

The fullstack MCP framework to develop MCP Apps for ChatGPT / Claude & MCP Servers for AI Agents.

项目地址：
https://gitcode.com/gh_mirrors/mc/mcp-use

点击查看 免费下载

@mcp-use/inspector 是 mcp-use 全栈框架内置的开源交互式调试工具，面向 MCP 服务器开发者与 MCP Apps 构建者：你可以在浏览器中连接任意 Streamable HTTP MCP 服务器，以类型化表单执行工具、浏览资源与提示词、预览并调试 widget、用 BYOK 或托管 LLM 试跑对话，甚至把客户端接入命令直接复制给 Cursor、Claude Desktop、Gemini CLI 等。本文以仓库中 libraries/typescript/packages/inspector/CHANGELOG.md 为主干，结合 README 与 Inspector 文档，系统梳理它的架构、安装运行方式、CLI 参数、连接与认证模型、Chat 能力演进及嵌入式集成方法，并给出源码级依据，帮助你在自己的项目里把 Inspector 用透。

一、Inspector 是什么：一个浏览器里的 MCP 调试控制台

@mcp-use/inspector 是一个开源、开箱即用的 MCP 调试工具，用 React + Tailwind 构建。它的定位在 README 中写得很明确：interactive developer tool for testing and debugging MCP servers，支持 MCP-UI 与 OpenAI Apps SDK 两种 widget 协议。

从包结构看（见 package.json），它对外暴露三部分：

三个子目录 src/client、src/server 与 tests 分别承载 UI、代理/OAuth BFF 与测试，playwright.config.ts、vitest.config.ts 与 tsup.client.ts/tsup.server.ts 等构建配置则支撑起「一次构建、多形态分发」（独立 CDN 包、嵌入式 bundle、Node 服务端）。

它有三种使用形态：

# 方式一：一行命令启动本地独立 Inspector
npx @mcp-use/inspector

# 方式二：在 mcp-use 项目中随开发服务器启动
npm run dev # Inspector 出现在 http://localhost:3000/mcp/inspector

二、连接任意 MCP 服务器：传输、URL 与三种连接模式

连接是 Inspector 的第一入口。在 Dashboard 右侧连接面板中填入 MCP endpoint 即可建立连接，例如 https://mcp.linear.app/mcp 或本地 http://localhost:3000/mcp。

连接模式的演进是 CHANGELOG 中反复出现的主题。早期版本（0.16.2 前后）连接表单让用户在 "Direct" 与 "Via Proxy" 之间二选一；v11.0.0 起（CHANGELOG 中 430178c）引入了 Auto 模式作为默认：

• Auto：先尝试浏览器直连，遇到 CORS 或其他可代理解决的连接错误时自动回退到已配置的 Inspector 代理；
• Direct：绝不使用代理；
• Proxy：立即走代理；
• Via Proxy 作为高级覆盖项保留在配置对话框中，connectionType 旧配置会被兼容性保留并写为新的 connectionMode 字段。

useMcp 在自动回退后会应用运行时代理配置来推导网关 URL 与请求头，保证回退重试走代理而不是继续用原直连传输（同上条目）。v20.0.0（a3d8591）进一步把连接模式升级为 MCP 代理路由的权威依据：Auto 模式先直连再回退代理、Direct 模式永不回退、Proxy 模式立即使用；切换模式时会清除过期代理设置；绕过浏览器 HTTP 缓存拉取 OAuth 元数据，避免跨 Inspector 源复用 CORS 响应。

协议版本选择

v20.2.3 起，连接表单与连接设置中直接暴露了 协议版本选择，配置项也更容易找到。这与底层客户端的能力直接相关：v20.0.0 将客户端栈迁移到官方 MCP TypeScript SDK v2（@modelcontextprotocol/client@2.0.0-beta.2）后，HTTP 连接默认 versionNegotiation: "auto"，先以 server/discover 探测、对 v1 服务器透明回退到 2025 initialize 握手；stdio 默认 SDK v1 模式；协商出的代际与版本通过 protocolEra: "legacy" | "modern" 与 protocolVersion 暴露在连接与 useMcp 结果上（见 CHANGELOG v20.0.0 a9ba017 条目）。

CLI 连接参数与自动连接

独立模式通过 CLI 文档 提供以下参数：

# 自动连接 + 指定端口 + 不自动开浏览器
npx @mcp-use/inspector –url http://localhost:3000/mcp –port 9000 –no-open

CLI 相关的两个环境变量（同见于 cli.mdx）：

• MCP_INSPECTOR_FRAME_ANCESTORS：控制哪些源可把 Inspector 嵌进 iframe（CSP frame-ancestors）。开发模式默认 *，生产模式默认 'self'，可传空格分隔的源列表或 *；
• MCP_URL：反向代理场景（ngrok、E2B、Cloudflare tunnel）下设置的外部基址，用于 widget 资源 URL 与 Vite HMR WebSocket 的推导；已设置时 CLI 不会覆盖。

另外 v20.0.1（33e30cb）出于 SSRF 防护，将 mountInspector 的 oauthProxyAllowLoopback 默认改为 false（公开部署的 Inspector 不再代理到宿主回环服务），独立 CLI 本地开发仍放行回环，但生产（NODE_ENV=production，发布的 Docker 镜像即此）默认阻断，可用 INSPECTOR_ALLOW_LOOPBACK=true 显式覆盖。

三、服务器详情视图：Tools、Resources、Prompts、Skills 与 Elicitation

连接成功后点 Inspect 进入服务器详情视图，CHANGELOG 与 Inspector 文档 共同勾勒出完整的面板矩阵：

Tools 标签页

浏览全部工具及描述、选择工具查看 JSON Schema、填入参数点击 Execute 实时执行、语法高亮查看结果。CHANGELOG 中该区域的持续打磨包括：

• 批量粘贴与自动填充（v0.21.0 179e800）：ToolsTab 支持直接把 JSON 或 JS 对象语法粘贴进输入框，粘贴会覆盖已有值时弹出 auto-fill 确认对话框，并自动将 JS 对象语法转换为合法 JSON；
• 类型强制与 schema 解析（v0.19.0 3334a67）：工具参数处理支持类型强制转换与 schema 解析，配套 SEP-1330 的 elicitation enum schema 变体支持；
• 工具元数据展示（v0.20.0 f4e2a70）：ToolsList 按工具类型显示 MCP/OpenAI 图标与参数数量；
• required 语义修复（v7.0.0 83271e8）：ToolInputForm 不再把 required: boolean 写到每个属性上（JSON Schema 中 required 是父级的 string[]），避免了 Anthropic 2020-12 校验器拒绝非法 input_schema 的问题；
• 工具生命周期通知（v20.0.0 da86879 等）：widget 挂载、工具调用 start/delta/complete 帧的流式交付。

Resources 与 Prompts 标签页

Resources 按 URI 浏览服务器暴露的内容、查看 MIME 类型与元数据、复制资源 URI、预览内容；Prompts 用于测试带参数的提示模板：选择 prompt、填参数、点 Render、复制渲染结果。v0.18.4 起两个标签页都带手动刷新按钮（ListTabHeader + 旋转加载图标），无需重连即可拉取最新列表。

Skills 标签页（Skills over MCP）

v20.1.0（2daf9c9）引入类型化的 Skills over MCP 客户端操作与 带完整性校验的文件浏览器。其工作方式（结合 index.mdx）：

• 服务器未声明 io.modelcontextprotocol/skills 扩展时，标签禁用并说明原因；声明了但目录为空则显示红色错误态；
• 每个 skill 以文件夹形式呈现，内含 SKILL.md 与支持资源，点选按需读取；
• 预览前校验 skill manifest 声明的 SHA-256 摘要，SKILL.md 还会校验解析出的 YAML frontmatter 与目录条目一致，摘要不匹配会阻断预览；
• Markdown、纯文本、位图、音频、视频可内联预览；脚本、HTML、SVG 等二进制文件永不执行，只能显式下载；
• Chat 中渐进式注入技能上下文：模型需要时按需懒加载 SKILL.md，且可移除；allowed-tools 不会被技能内容扩大权限。

Elicitation 标签页

处理工具执行过程中需要用户输入的请求：排队查看、表单模式填写提交、接受/拒绝/取消，响应后跳回工具结果。支持的字段类型覆盖文本、数字、布尔、单选枚举（string + enum、string + oneOf[{const,title}]、legacy enumNames）与多选枚举组（array + items.enum、array + items.anyOf[{const,title}]），与 SEP-1330 枚举 schema 变体对齐。v3.0.0 起从 Chat 标签触发的 elicitation 改为 内联在对话流中（原 Toast 跳转仅保留给 Tools 标签触发的情况），Elicitation 标签页仍作为兜底审计视图存在。

四、OAuth、mixed-auth 与安全模型：从弹窗到同标签页重定向

OAuth 是 Inspector 连接受保护服务器（如 Linear）的核心能力。CHANGELOG 记录了这条安全与体验并重的演进线：

• 预注册 OAuth Client ID（v5.0.0 78cfc8a）：UseMcpOptions/McpServerOptions 新增 oauth: { clientId?, clientSecret?, scope? }。提供 clientId 时跳过动态客户端注册（DCR）——这对 Slack、WorkOS 等剥掉 registration_endpoint 的代理型 MCP 服务器是硬需求；提供 clientSecret 时自动把 token endpoint 认证从 none 切到 client_secret_basic/client_secret_post，适配不支持 PKCE 的提供商。认证对话框中对应出现 Client ID / Client Secret / Scope 字段；
• 单标签页 OAuth 流（v3.0.1 47b446e/c1ea21a）：早期版本授权页在新标签页打开，回调把第二个标签页导航回 Inspector，留下两个标签页；现改用同标签页重定向（useRedirectFlow: true + preventAutoAuth: true），授权完成后原标签页直接回到 Inspector；OAuth 回调收到错误时先从存储的 state 找回 returnUrl 再重定向回 Inspector，以应用级 toast 呈现错误，而不是裸露堆栈页；
• mixed-auth 支持（v20.1.1 e17cd7b）：可匿名连接、公开工具立即可用的服务器不再被认证阻塞；发布 OAuth protected-resource 元数据时，服务器卡片显示 "This server is using mixed auth" 与 Authenticate 按钮，可提前认证或在受保护操作触发 wire-level OAuth 挑战时再认证；Chat 中受保护工具调用被暂停并显示琥珀色 Authenticate 动作，弹窗授权后同一轮对话自动续跑，全页 OAuth 重定向后自动重放被中断的回合；
• OAuth BFF 加固（v20.0.0 a9ba017、ac3d1eb）：Inspector OAuth BFF 把请求绑定到 SDK 发现的元数据/端点，对 SSRF/私有目标与重定向 fail closed，限制 body 与超时、剥离不安全请求头、限制 CORS 源；OAuth 会话值以 AES-256-GCM 密文存储在 IndexedDB（不可导出的 origin key），secret 连接字段与客户端密钥为运行时内存态、刷新后需重新提供，Inspector 资产与代理/OAuth API 均限流；
• OAuth 元数据兼容性（v20.2.1 aba4346）：允许同源 segment-aware 父路径的 protected-resource 元数据（对齐官方 MCP TypeScript SDK 兼容策略），根 well-known 发现按根资源标识校验，跨源、兄弟路径、带凭据、带 fragment 及不安全的非回环资源值仍被拒绝。

对 localhost 服务器的特殊处理：托管模式下 Chat 走云端后端，服务端连不到用户本机的 localhost（会以 502 呈现为 CORS/Failed to fetch），因此 v10.0.1（efa7fe7）让回环 URL 回退到浏览器端直连流式聊天，并在配置密钥的空状态解释托管密钥不可用的原因、提示需要个人 API Key。

五、Chat 标签页：从 BYOK 到托管 LLM 与多模态

Chat 用 LLM 与服务器工具做端到端对话测试。它走过一条从「浏览器内 BYOK」到「托管 + 自管双通道」的演进：

提供商矩阵（BYOK 部分）

BYOK 模式下 API Key 只存于浏览器本地、请求直接从设备发往 LLM 提供商，这是 README 明确承诺的隐私边界。

托管 Chat 与云端通道

• v20.0.0（b4c192e）启用 localhost 托管 Inspector Chat：通过浏览器端 MCPAgent 与云 LLM 代理，匿名用户需登录，认证用户消费云 llm_tokens 额度；
• 运行时配置托管 Chat URL（v2.2.0 e9c4bd0）：服务端读取 MANUFACT_CHAT_URL 注入 window.__MANUFACT_CHAT_URL__，优先于构建期 VITE_MANUFACT_CHAT_URL，同一 npm 包可按部署（Railway、CDN、自托管）配置而无需重建；
• 托管模式 localhost 回退（v10.0.1）：见上文第四节；
• Managed chat 徽标修复（v20.3.9 b1bda25）：选中 Claude/Gemini 时不再错误显示默认 OpenAI logo，使用所选云模型的名称与 logo；
• 付费层提示优化（v11.0.0 430178c）：ChatTab 通过 useHostedSession 解析共享会话，仅对匿名访客展示免费层登录/升级引导（抽取为纯函数 shouldShowFreeTierUpgrade 并单元测试）。

多模态、流式与工具调用可视化

• 多模态图片附件（v0.18.0 32f2113）：回形针按钮上传图片发给视觉模型；MCP prompt 返回的图片正确渲染而非展示原始 JSON；
• MCP image 工具结果转发（v7.0.0 83271e8）：把 MCP content 块转换为 provider 中立的 ContentPart[]——Anthropic 把图片嵌入 tool_result.content 的 image block，OpenAI 以 text 摘要 + 后续 user turn 的 image_url 携带图片字节，Gemini 以 functionResponse.response 摘要 + 后续 user turn 的 inlineData 携带；纯文本工具结果直接以字符串交付，音频/资源块以文本标记摘要；
• 流式工具参数（v20.0.0 3294086）：模型生成工具参数时，部分参数实时流入抽屉与 MCP App 视图；Anthropic 工具请求开启 eager input streaming，部分 JSON 修复能正确处理代码与 SVG 字符串，视图宿主不会用陈旧的完整输入覆盖更新的部分输入；
• 工具 schema 清洗（v2.2.0 e9c4bd0）：发给 Gemini 前自动剥离其拒绝的关键词（$schema、additionalProperties、$ref 等）；Gemini 不增量流式输出工具参数，因此部分参数动画每个工具调用只更新一次；
• Token 统计修复（v20.2.5 d0107b3）：cacheCreationInputTokens 在聚合、LLM span usage 与 raw-chat payload 的 tokenUsage 中均保留；OpenAI 缓存读取不再被重复计数；回退总计只加 Anthropic 形态的 cache_read_input_tokens；
• 协议感知的采样能力（v20.0.0 af09aee）：legacy 有状态连接启用 server-to-client sampling 并展示内容，modern 无状态连接隐藏内容、禁用导航标签并提示原因、省略 sampling 客户端能力；
• 128 工具上限提示（v20.3.2 f2f4fdb）：服务器超过 OpenAI/Gemini 文档化 128 工具上限时在 Chat 中告警。

Chat 的工程化重构

v2.2.0（e9c4bd0）移除了全部 @langchain/* 硬依赖与 MCPAgent，Chat/sampling/props-generation 路径改为直接调用 OpenAI、Anthropic、Google REST API 并自研 MCP 工具调用循环，消除宿主 Next.js/Vite 中 Cannot find package 'langchain' 的运行时报错；SSE 线上格式（message/text/tool-call/tool-result/done/error）保持不变以兼容 Vercel AI SDK data-stream 解析。仓库配有一条回归测试（mcp-use/tests/inspector-no-langchain.test.ts），一旦 @langchain/*、langchain 或 MCPAgent 重新进入 Inspector 的 package.json 或构建产物即失败。

六、Widget 调试：MCP Apps 与 OpenAI Apps SDK 双协议预览

当工具返回 MCP App widget 时，Inspector 在工具结果下方渲染 widget 并提供调试控制，这是它区别于普通 MCP 客户端的关键能力（详见 调试文档 与 index.mdx）：

• 双协议渲染（v0.17.0 1dcba40）：MCPAppsRenderer 与 OpenAIComponentRenderer 并存，widget 同时兼容 MCP Apps（io.modelcontextprotocol/ui）与 ChatGPT Apps SDK，配 widget adapter 与协议辅助函数；
• 沙箱 iframe：隔离渲染 + iframe 控制台（可展开日志、级别过滤、搜索、可调高度，v0.22.0 5a73b41）+ 安全区 insets；沙箱权限演进中移除了 allow-same-origin 与 allow-popups-to-escape-sandbox 以强化安全（v0.18.5 3d787ba）；
• 调试控制：查看传入 widget 的 props/output/元数据、切换 inline / 画中画 / 全屏显示模式、桌面/平板/移动布局、主题/语言/时区/hover/touch/安全区，以及 CSP 行为验证；
• CSP 违规面板（v0.22.0）：widget 触发 CSP 违规时给出面板与清除动作，切换 CSP 模式后 widget 自动重新执行；Apps SDK widget 同样支持 CSP 模式；
• 生命周期状态模拟（v0.18.4 ac3e216）：模拟 ChatGPT 的 pending 状态，工具结果未返回时 widget 先渲染 loading，完成后无缝更新（配套 conformance server 的 delayed weather 工具演示生命周期）；
• Invoking/Invoked 状态文本（v0.22.1 4546a8c）：widget 元数据新增 invoking/invoked 可定制状态文案；v8.0.1 修复了状态标签绝对定位 wrapper 拦截 iframe 指针事件的问题（pointer-events-none）；
• 悬浮层修复（v20.3.10 46cc2cf）：高 MCP App 不再溢出工具结果视图，结果内容可增长滚动而不被响应工具栏遮挡顶部。

mcp-use screenshot 无头截图（v6.0.0 46caf80，v7.0.0 83271e8 增强）：CLI 调用工具 → 无头渲染结果视图 → 保存 PNG，用于 MCP Apps 的视觉反馈闭环：

# 先保存一次 OAuth 会话（一次登录覆盖后续所有截图）
mcp-use client connect <url> –name <name>

# 调用工具并截图 widget 视图（自动匹配 widget 自然渲染尺寸）
mcp-use screenshot –tool <name> key=value key2:=<json>

实现细节：CLI 在空闲端口起一个全新的独立 Inspector 实例，通过 Chrome DevTools Protocol 驱动系统 Chrome/Chromium/Edge/Brave 访问 /inspector/preview/:view 路由；浏览器路径可被 MCP_USE_CHROME_PATH、PUPPETEER_EXECUTABLE_PATH、CHROME_PATH 覆盖；支持 –cdp-url 连接远程 Chromium 提供商；client tools call 遇到声明 UI 资源的工具（_meta.ui.resourceUri 或 openai/outputTemplate）会自动截图（–no-screenshot 可关闭）。v20.3.4（32da345）起，MCP App 初始化失败（坏资源、sandbox 连接失败、握手失败）时以稳定的 view_load_failed 码失败而非写出 PNG，初始化成功后的 console.error/未捕获错误仍被忽略以避免误报。

七、嵌入式集成：mountInspector 与样式契约

把 Inspector 挂进自有应用（Hono/Express/mcp-use）使用 mountInspector()，它提供完整能力：打包 UI、代理、OAuth BFF 与回调（见 集成文档）：

import { Hono } from "hono";
import { mountInspector } from "@mcp-use/inspector";

const app = new Hono();
app.get("/api/health", (c) => c.json({ status: "ok" }));

// Inspector 出现在 /mcp/inspector
mountInspector(app, { basePath: "/mcp" });

export default app;

也可返回框架中立的 Fetch handler：

const inspect = mountInspector({
basePath: "/mcp",
autoConnectUrl: "http://localhost:3000/mcp",
});
const response = await inspect(request);

两条值得注意的实现细节：

@import "tailwindcss";
@import "@mcp-use/inspector/client/styles.css";

@source "../node_modules/@mcp-use/inspector/dist/client";

独立 Inspector 已内置这些样式。v20.2.0 还通过嵌入式 Chat bridge 暴露了 CSP 模式与审计命令，宿主与编码 agent 可以在 Widget-Declared 模式下校验 MCP Apps；v20.3.0（99f76cc）起从 @mcp-use/inspector/client 导出连接设置表单、状态 hook 与公开配置类型（含可选 consumer URL 校验）。

八、持久化、隐私与遥测

• 持久化（README）：服务器连接跨刷新保留；OAuth 会话以 AES-256-GCM 密文存 IndexedDB（不可导出 origin key）；secret 请求头与客户端密钥运行时内存态、刷新后重新提供；会话偏好自动维护，随时可 Clear All 清空；
• 数据边界：认证 token 与凭据只存浏览器，不发送到任何服务器；BYOK Key 仅存本地；
• 遥测与退出：匿名化使用数据经 PostHog 采集（v20.0.0 c878835 移除 Scarf 遥测，PostHog 为唯一提供商）；通过 MCP_USE_ANONYMIZED_TELEMETRY=false（环境变量或 localStorage）整体关闭，旧键 mcp_inspector_telemetry_disabled 会自动迁移。v5.0.0 修复了此前环境变量只关 Node 侧、浏览器 useMcp 仍初始化 posthog-js 的问题——服务端现在把该标志镜像为每页运行时标记 window.__MCP_USE_ANONYMIZED_TELEMETRY__，浏览器与 Node 两条遥测路径统一受控。

九、版本演进时间线：从 0.x 到 20.x 的关键里程碑

基于 CHANGELOG 可梳理出 Inspector 的能力演进主线（版本号对应 inspector 自身，稳定版与 canary 并行）：

其中 v20.0.0 是最深的一次重构：@mcp-use/client 与 @mcp-use/agent 变为 ESM-only（Node 22.22.2+），CommonJS require() 入口不再发布；v1 别名（samplingCallback、elicitationCallback、auth_token、customHeaders 等）移除，改用 onSampling、onElicitation、authToken、headers 等；posthog-js/posthog-node 换成 fetch-only 捕获，客户端运行时依赖收敛到仅 @modelcontextprotocol/client 一个（v20.3.9 又把 auth_token 标记为废弃，v2 已改名 authToken，设置蛇形拼写不再产生 Authorization 头）。Runtime verification 覆盖 Node、Deno、浏览器与 React，对着真实 v1/v2 服务器跑四服务器矩阵测试。

十、结语：一个版本即一份使用说明书

Inspector 的 CHANGELOG 不只是变更流水账——它本身就是最诚实的「用户手册」，记录了连接模式、OAuth 行为、Chat 提供商、widget 调试与安全模型的每一次行为变更。对使用者而言，把握住三条主线就足以驾驭它：

相关阅读：Inspector 使用总览 · CLI 用法 · 连接设置 · Widget 调试 · 命令面板 · URL 参数 · 自托管 · 变更记录文档

赞

分享

• 后端
• MCP 服务
• MCP Clients
• AI Agent
• 人工智能

【免费下载链接】mcp-use

The fullstack MCP framework to develop MCP Apps for ChatGPT / Claude & MCP Servers for AI Agents.

项目地址：
https://gitcode.com/gh_mirrors/mc/mcp-use

点击查看 免费下载

相关推荐

• MCP Inspector完全指南：可视化调试MCP服务器的高效工具

  MCP Inspector完全指南：可视化调试MCP服务器的高效工具 想要快速掌握MCP服务器的调试技巧吗？MCP Inspector就是你需要的终极解决方案！

  开发工具
  MCP Clients
  调试器

• MCP Inspector终极教程：可视化调试MCP服务器的完整指南

  MCP Inspector终极教程：可视化调试MCP服务器的完整指南 MCP Inspector是一款专为MCP服务器设计的可视化调试工具，能够帮助开发者和运维

  开发工具
  MCP Clients
  调试器

• MCP Inspector完全指南：可视化调试MCP服务器的专业解决方案

  MCP Inspector完全指南：可视化调试MCP服务器的专业解决方案 想要轻松调试MCP服务器却不知从何入手？MCP Inspector正是你需要的可视化调

  开发工具
  MCP Clients
  调试器

上一篇：
WeChatPad：3分钟搞定微信双设备同时在线，告别扫码烦恼！

下一篇：
从 config_flow 到实体：ha-emporia-vue 源码架构全解析，看懂 HA 集成开发范式

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考