奇 奇连 AI
学习路线图课程工具计算器企业服务关于加入会员

Macro 的 MCP 连不上怎么查：鉴权、动态客户端注册与自托管地址的定位路径

2026-08-17
站内工具 AI 编程工具报错分诊器 → 把报错原文贴进去，先分清是网络、额度、配置还是上游故障，再决定往哪个方向查。

Macro 的 MCP 接入，官方文档给的东西少得有点反常：一个远程地址、一次浏览器里的 OAuth、三段客户端配置，一页写完。配置面小本来是好事，可一旦客户端那边显示连接失败，你会发现能改的地方也就那么几处，改完还是连不上，就彻底没方向了。

更麻烦的是「MCP 连不上」这句话在 Macro 场景里至少指两件不同的事：一件是你的 AI 客户端连不上 Macro 的 MCP 服务器，另一件是 Macro 这边去连别人的 MCP 服务器连不上。这两件事的排查方向完全相反，官方文档只覆盖了前者。先把方向分清楚，比急着改配置有用得多。

这篇不重复讲 Macro 的 MCP 服务能做什么（那部分见 Macro 的 MCP 服务能做什么），只讲连不上的时候按什么顺序往下查、每一步能拿官方文档的哪句话对照、以及查到哪儿就没有官方答案了。

第一步：先分清你连的是哪一端

官方文档《MCP Setup》整篇讲的都是「把 AI 客户端接到 Macro 的 MCP 服务器」，标题里的 Connect AI clients to the Macro MCP server 说得很直白。它给出的端点是：

https://mcp-server.macro.com/mcp

文档明确写了两点：这个服务器是远程的，不需要本地跑任何进程；鉴权在客户端发起连接时走 Macro 的 OAuth 流程。另外还有一句常被忽略的：MCP 访问在 Macro 的每个套餐上都可用，包括 Free。这句话的排查价值在于，你可以直接排除「是不是套餐不够」这个猜测——按官方口径，它跟套餐无关。

反过来的方向，也就是 Macro 作为客户端去连接第三方 MCP 服务器，这一页文档一个字没提。仓库的 issue 列表里能看到有人在这个方向上报过问题（后面会提到），但官方文档没有对应章节，也就意味着你在那个方向上遇到的现象，暂时找不到官方给的处置办法。

所以第一个动作不是改配置，是问自己：报错来自你的编辑器/CLI 客户端，还是来自 Macro 内部的连接器界面？前者往下按本文顺序查，后者直接跳到最后一节。

第二步：地址和传输方式有没有写对

三种客户端的写法官方各给了一段，参数名不一样，最容易在这一步抄串。原文如下。

Claude Code：

claude mcp add --transport http macro https://mcp-server.macro.com/mcp

Codex CLI：

codex mcp add macro --url https://mcp-server.macro.com/mcp

接受 JSON 配置的编辑器，在 mcpServers 下加：

{
  "macro": {
    "type": "http",
    "url": "https://mcp-server.macro.com/mcp"
  }
}

把三段并排看，差异一目了然：

客户端传输方式怎么声明地址怎么传服务器名
Claude Code--transport http位置参数，跟在名字后面macro
Codex CLI命令里没有传输参数--url 具名参数macro
JSON 配置"type": "http""url" 字段对象的键名 macro

这一步值得逐字核对的点有三个：一是传输类型，官方给的是 http，Claude Code 那条命令里必须带 --transport http；二是路径结尾的 /mcp 不能丢，主机名单独拿去访问不是端点；三是 Codex CLI 用的是 --url，Claude Code 是位置参数，两边的习惯不通用，凭印象写会直接把地址塞成名字。

第三步：OAuth 那一步走完了没有

官方对鉴权的描述只有一句：认证发生在客户端连接时，走 Macro 的 OAuth 流程。三段配置后面各跟了一句操作说明，意思一致——启动客户端、调用名为 macro 的 MCP 服务器、然后在浏览器里把登录流程走完。

这意味着「配置写完」和「连上了」中间还隔着一次浏览器交互。如果客户端跑在没有浏览器的环境里（比如纯终端的远程主机、CI、容器），或者浏览器登录窗口被拦下、跳转回来时客户端已经退出，配置本身没错，连接一样建立不起来。官方文档没有给这种环境下的替代方案，也没有提供离线换取凭据的路径。

有一个相关信息值得知道：仓库里有一条标题为 [Feature Request] MCP Connector Auth tokens / headers 的开放条目，被打上了 planned 标签。也就是说「用 token 或自定义请求头做鉴权」这件事，官方标注为计划中，目前尚未提供。你现在能用的鉴权方式，就是文档里写的那一条 OAuth 浏览器流程。注意这只是一条被列入计划的功能请求，不能当成已有能力去配。

第四步：动态客户端注册这条线

仓库里另有一条开放条目，标题是 fix(mcp): cannot connect MCP servers without Dynamic Client Registration (e.g. HubSpot)。标题里的 Dynamic Client Registration（动态客户端注册）是 OAuth 侧的通用概念，指客户端事先没有登记过身份时，由服务端在连接过程中动态签发一组客户端凭据；Macro 官方文档没有展开说明这块。

这条标题能说明的只有一件事：有人报过「连接不支持动态客户端注册的 MCP 服务器时连不上」，并且举了 HubSpot 作例子。它不能用来推断 Macro 当前的实现是什么样、有没有被修复、什么时候修。标题里 e.g. HubSpot 这个例子也提示，它讲的是 Macro 去连第三方服务这个方向，跟本文第二三步的方向相反。

对你的实际意义是：如果你连的是 Macro 自己的端点，这条大概率跟你无关；如果你是在 Macro 里接第三方 MCP 服务、对方又要求预先注册好的 client id，那么你遇到的可能是同一类情况，而官方文档目前没有给出解决方案。

第五步：受保护资源元数据（RFC 9728）

还有一条开放条目的标题是 fix(mcp): protected resource metadata missing RFC 9728 resource field，说的是受保护资源元数据里缺少 RFC 9728 规定的 resource 字段。

这条要格外克制地读。标题没有写明缺字段的是哪一端、影响哪些客户端、是否已经处理。按 MCP 的鉴权约定，客户端会先去读服务端暴露的元数据来决定往哪儿发起授权，元数据里少字段确实可能让部分严格实现的客户端在握手阶段就停住——但「可能」到此为止，具体到 Macro 是不是这个链路、修没修，标题给不了答案，官方文档里也没有对应章节。

所以这一步的正确做法不是照着标题去改什么，而是：如果你的客户端报的是授权发现阶段的错（拿不到 metadata、拿不到 authorization server 信息之类），你至少知道有人报过相近的现象，不用怀疑是自己配置写错了；至于怎么绕开，官方尚未给出解决方案。

第六步：自托管的情况要单独算

如果你跑的是自托管的 Macro，上面几步的前提都要重新审视。官方那页文档给的是 https://mcp-server.macro.com/mcp 这个远程地址，它对应的是托管服务，不是你本地实例的地址。

仓库里有两条重复出现的开放条目，标题都是 Does mcp_service run under run_local, or is MCP local-workspace access not yet supported for self-hosted?——直译过来就是在问：mcp_service 会不会在 run_local 下启动，还是说自托管暂时不支持 MCP 访问本地工作区。这条本身是个提问，不是结论，说明这件事在社区里还没有明确答案；官方文档同样没有写自托管场景下 MCP 该怎么配。

另外一条相关的是 OAuth redirect URI hardcoded to localhost:8085, doesn't account for --instance/--port-base，讲 OAuth 回调地址与自定义实例、端口基址对不上。这条不限于 MCP，但既然第三步的鉴权要靠浏览器回调，端口对不上就会卡在同一个环节。自托管的其它坑另见 Macro 自托管的已知问题，本地跑起来的完整步骤见 Macro 自托管本地调起。

一张按现象走的对照表

现象先看哪一步官方文档有没有给办法
客户端根本识别不到 macro 这个服务器第二步：命令参数与 /mcp 路径有，三段配置原文
连接发起了，停在浏览器登录第三步：OAuth 是否走完、环境有没有浏览器部分有，只说明要在浏览器完成
想用 token/请求头代替浏览器登录第三步没有，官方标注为计划中
在 Macro 里接第三方 MCP，对方不支持动态注册第四步没有
报错出现在授权发现/元数据阶段第五步没有
自托管实例上的 MCP 与本地工作区第六步没有

表格右列有一半是「没有」，这不是敷衍，是这个专题当前的真实状态：官方那页文档解决的是「标准托管环境 + 标准客户端」这一种情况，超出这个范围，你能拿到的只有别人报过同类现象这个事实。

什么时候这篇帮不上忙

三种情况下别照这篇往下查。

第一，你的报错跟工具调用有关而不是连接本身——比如已经连上了，但某个工具的参数传过去类型不对。仓库里有一条 fix(soup): ListEntities AST filter params emit no type, so schema-driven MCP clients send them as strings 提到了这类现象，说的是过滤参数没有声明类型、按 schema 生成请求的客户端会把它们当字符串发。这属于工具层，不属于连接层，具体工具的参数约定见 Macro MCP 的实体类工具。

第二，你用的客户端不在官方给出的三类里。官方只写了 Claude Code、Codex CLI 和接受 JSON 配置的编辑器三种；别的客户端能不能连、要怎么写，文档没说，本文也不替它推断。

第三，你需要的是确定性的修复时间点。上面引的几条都是仓库里的开放条目，我们只用它们说明「有人遇到过」，不拿它们当结论，更不能据此判断修复进度。真要确认状态，只能自己回到仓库里看那几条的最新讨论。

按这六步走一遍，多数情况会在第二步或第三步收敛——地址参数写串、浏览器流程没走完，是配置面这么小的接入方式里仅有的两个高频出错位置。剩下的四步更多是帮你确认「这不是你的问题」，省下继续改配置的时间。

延伸阅读

本文依据 Macro 官方仓库（github.com/macro-inc/macro，AGPL-3.0 协议）的 apps/docs/ 产品文档、 MCP 工具参考与自托管说明整理，核对日 2026-08-17。 我们没有注册或运行过 Macro，因此不涉及界面外观与操作手感； 官方标注为计划中的能力文中已如实标明，不代表当前可用。 价格与额度以官网 macro.com 最新页面为准；许可证相关问题请咨询专业人士并以官方许可证原文为准。

想系统学会用 AI？报名体系课或加入会员，照着学、照着用。

浏览课程 加入会员