背景：当嵌入式开发遇上 AI 工作流

乐鑫（Espressif）在 2025 年推出了官方 MCP 服务器（https://mcp.espressif.com/docs），将 ESP-IDF 编程指南、芯片规格书、技术参考手册等核心文档接入了 AI 工作流。开发者在编写 ESP32 相关代码时，AI 助手可以实时检索乐鑫官方文档，获得准确、可追溯的技术支持。

这个 MCP 服务器提供了一个核心工具 —— search_espressif_sources，支持对乐鑫文档库进行语义检索，覆盖中英文内容。典型的使用场景包括：根据硬件型号自动生成符合规范的代码、结合报错信息定位官方修复方案、对照最新文档审查 API 用法，以及参考迁移指南完成 ESP-IDF 跨版本升级。

然而，乐鑫的 MCP 服务器采用了 GitHub OAuth 认证，并且使用的是 Streamable HTTP 传输协议。这意味着并非所有 MCP 客户端都能直接连接 —— QoderWork 就是其中之一。本文将记录从踩坑到最终跑通的完整过程。

踩坑记录：直接连接为什么会失败

第一次尝试：HTTP 直连

在 QoderWork 中添加自定义 MCP 服务器时，最直接的做法是将乐鑫的 URL 以 HTTP 方式填入：

名称：乐鑫 URL：https://mcp.espressif.com/docs 传输方式：HTTP

结果：连接失败，日志中报出 SSE error: Non-200 status code (405)。

这个 405 (Method Not Allowed) 错误说明 QoderWork 以 SSE（Server-Sent Events）方式尝试 GET 请求，但乐鑫的服务器端点不接受 GET 方法 —— 它使用的是较新的 Streamable HTTP 传输协议，需要 POST 请求。

第二次尝试：重新配置后仍然 401

重新配置后再次连接，错误信息变了：服务器返回 401 Unauthorized。QoderWork 尝试自动发现 OAuth 元数据（按照 MCP 规范去请求 /.well-known/oauth-authorization-server），但乐鑫的服务器没有暴露这个标准端点，导致 OAuth 握手失败。

日志中的关键信息：

[INFO]  Server returned 401, discovering OAuth metadata
[ERROR] Server returned 401 but no OAuth metadata found
[ERROR] Failed to fetch OAuth metadata

到这里问题已经很清楚了：QoderWork 内置的 MCP 客户端尚不支持乐鑫所采用的非标准 OAuth 发现流程与 Streamable HTTP 传输协议的组合。

解决方案：用 mcp-remote 做桥接

核心思路

观察乐鑫官方支持的客户端列表（Cursor、VS Code、Claude Desktop），会发现一个规律：像 Claude Desktop 这类不支持直连远程 MCP 的客户端，官方推荐使用 npx mcp-remote 作为本地代理。

mcp-remote 是一个开源的 Node.js 工具，它的作用是：在本地启动一个 stdio 进程，将 QoderWork 的 MCP 请求转发到远端的 Streamable HTTP 服务器，同时独立处理 OAuth 认证流程（通过浏览器完成 GitHub 登录）。这样 QoderWork 只需要与本地的 stdio 进程通信，不再需要自己处理复杂的远程认证。

架构变化如下：

修改前（失败）：
QoderWork --HTTP/SSE--> 乐鑫 MCP 服务器 (401 / 405)

修改后（成功）：
QoderWork --stdio--> mcp-remote (本地代理) --Streamable HTTP--> 乐鑫 MCP 服务器
                         |
                    浏览器 OAuth (GitHub 登录)

前提条件：安装 Node.js

mcp-remote 依赖 Node.js 运行环境。如果你的系统上还没有安装 Node.js，可以通过以下方式安装：

Windows（使用 winget）：

winget install OpenJS.NodeJS.LTS

macOS（使用 Homebrew）：

brew install node

安装完成后，确保 npx 命令可用：

npx --version

在 QoderWork 中配置乐鑫 MCP 服务器

第一步：移除旧的 HTTP 配置

如果之前已经尝试过直连方式，需要先将旧的"乐鑫"连接器删除或禁用。打开 QoderWork 的 设置 → 连接器，找到"乐鑫"并移除。

第二步：添加 stdio 类型的自定义 MCP 服务器

在 QoderWork 中添加新的自定义 MCP 服务器，配置如下：

{
  "mcpServers": {
    "乐鑫": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.espressif.com/docs"]
    }
  }
}

第三步：进行认证

配置保存后，QoderWork 会启动 mcp-remote 进程。首次连接时，mcp-remote 会自动：

1. 下载自身依赖（mcp-remote@0.1.38）
2. 发现乐鑫的 OAuth 服务器配置
3. 自动打开浏览器，跳转到 GitHub 登录页面
4. 等待你在浏览器中完成 GitHub 授权

在浏览器中用 GitHub 账号登录并授权后，mcp-remote 会获取到认证令牌，并建立与乐鑫 MCP 服务器的连接。这个令牌会被缓存在本地，后续连接无需重复登录。

第四步：验证连接

授权完成后，在 QoderWork 的连接器页面应该能看到"乐鑫"状态变为已连接，并且显示了 1 个可用工具（search_espressif_sources）。

日志中的成功标志：

[INFO] Connected to remote server using StreamableHTTPClientTransport
[INFO] Proxy established successfully between local STDIO and remote StreamableHTTPClientTransport
[INFO] Upstream server connected {"name":"乐鑫","toolCount":1}

实际使用体验

连接成功后，在与 QoderWork 对话时就可以直接使用乐鑫的文档检索能力了。以下是一些实际场景：

场景一：查询 ESP-IDF 的 WiFi 配置方法

直接向 QoderWork 提问："如何在 ESP-IDF 中配置 WiFi STA 模式？" QoderWork 会自动调用 search_espressif_sources 工具，检索乐鑫官方文档并基于返回的内容给出准确的回答，附带文档来源链接。

场景二：排查编译错误

将编译错误信息贴给 QoderWork，它会自动检索相关文档，定位错误的根本原因，并给出基于官方文档的修复方案。

场景三：跨版本迁移

当需要将项目从 ESP-IDF v5.x 升级到 v6.0 时，QoderWork 可以检索迁移指南，识别 API 变更点，并帮助修改项目代码。

经验总结

这次连接乐鑫 MCP 服务器的过程揭示了当前 MCP 生态中一个普遍存在的问题：不同客户端和服务器在传输协议（SSE vs Streamable HTTP）和认证方式上的实现差异。

几个关键要点值得记住：

当 MCP 客户端直连远程服务器遇到 405 或 401 错误时，大概率是传输协议或认证方式不兼容。mcp-remote 是一个很好的桥接工具，它能处理 Streamable HTTP 传输和 OAuth 认证，对客户端只暴露标准的 stdio 接口。对于 QoderWork 这类支持 stdio 类型 MCP 的客户端，通过 npx mcp-remote <url> 的方式几乎可以连接任何远程 MCP 服务器。

乐鑫的 MCP 服务器本身质量不错，文档检索的准确性和响应速度都令人满意，OAuth 认证一次配置后也不会反复打扰。对于 ESP-IDF 开发者来说，把这个工具接入日常使用的 AI 助手，能显著减少在文档和代码之间来回切换的时间。