10 月 29 号晚上，我给 Claude Code 接远程 MCP。浏览器明明显示“授权成功”，终端却还挂着 401。折腾半天才发现，登录页面成功，不等于令牌已经回到工具端。

Claude Code 的远程 MCP OAuth 卡住时，可以沿着“端点 → OAuth 元数据 → 浏览器回调 → Token”往下查。最常见的是回调端口被占、redirect URI 逐字符对不上，或者旧令牌缓存让刷新请求一直返回 invalid_grant。

截至 2026 年 11 月 4 日，现有资料没有给出可信的固定回调端口、缓存绝对路径或性能数据。这篇不会拍脑袋编个路径让你删。

这篇适合谁

• 已经执行 claude mcp add，但 /mcp 里一直显示未连接。
• 浏览器授权成功，Claude Code、Cline 或 Zed 却拿不到令牌。
• 正在 SSH、容器、WSL 或远程开发环境里跑 MCP。
• 遇到 401、404、redirect_uri_mismatch、invalid_grant，不知道该查哪一层。

如果你只是想添加一个不需要 OAuth 的本地 stdio MCP，没必要从头看，直接跳到工具配置对照。

整体流程

1. 记录 Claude Code、Node.js 和 MCP 配置版本。
2. 确认远程端点使用 HTTP 还是旧式 SSE。
3. 注册 MCP，再通过 /mcp 单独触发 OAuth。
4. 核对 OAuth discovery 与 redirect URI。
5. 检查回调端口是否真的由当前终端监听。
6. 定位令牌缓存，判断是没写入还是刷新失败。
7. 用 Cline、Zed 或官方 SDK 做交叉验证。

flowchart LR
 A[Claude Code 注册 MCP] --> B[读取 OAuth 元数据]
 B --> C[浏览器授权]
 C --> D[localhost 回调端口]
 D --> E[交换 Access Token]
 E --> F[写入凭据缓存]
 F --> G[访问远程 MCP]
 G -->|Token 过期| H[刷新令牌]
 H --> F

别一看到 401 就重装 Claude Code。真的，没用。

先看现象

你的现象	优先检查	原因
配完 URL 没弹登录页	/mcp 管理界面	注册服务与 OAuth 登录是两步
404 或 405	MCP 路径、transport	HTTP、SSE 或 URL 配错
浏览器成功，工具仍未连接	回调端口与终端进程	浏览器没有把 code 交回当前客户端
redirect_uri_mismatch	完整 redirect URI	host、端口、协议、尾斜杠必须一致
重启后又要求登录	凭据缓存	Token 没写入或凭据库不可用
用一阵后突然 401	Refresh Token	过期、撤销、时钟偏差或 scope 变化

远程 MCP OAuth 通常不单独收费，但远程服务、SaaS 账号或背后的模型 API 可能计费。现有素材里没有可核实的价格和额度，我这里不填数字。

还有个容易混淆的前提：MCP 服务地址和模型 API 地址不是一回事。OpenRouter、ofox.io 这类聚合网关解决的是模型请求路径，而远程 MCP OAuth 负责工具服务授权；两套凭据不能互换。ofox.io 支持 OpenAI、Anthropic 与 Gemini 三类协议，但它的模型 API Key 不能拿来替代某个远程 MCP 服务签发的 OAuth Token。

先把环境信息留住

别急着删配置，先记录现场。

claude --version
node --version
claude mcp list

一手资料里没有 Claude Code 的固定版本号，以本机 claude --version 为准。资料只确认 npm 上的通用 oauth 包版本为 v0.10.2。它不是 Claude Code 内置 OAuth 组件的版本，别拿这个数字判断客户端新旧。

要看某个服务的当前配置，可以运行：

claude mcp get remote-demo

具体输出字段可能随本机版本变化。排错时至少保留服务名、URL、transport 和作用域，Token 记得打码。

注册远程 MCP

新服务优先使用 Streamable HTTP：

claude mcp add --transport http remote-demo https://example.com/mcp
claude mcp list
claude

进入 Claude Code 后执行 /mcp，选择 remote-demo 并触发认证。菜单文案可能随版本变化，但有件事不会变：mcp add 只是注册连接，不代表 OAuth 已经完成。

团队项目可以使用项目级配置：

claude mcp add --scope project --transport http team-mcp https://example.com/mcp
claude mcp get team-mcp
git status

local、project、user 等作用域到底支持哪些，以当前 Claude Code 帮助信息为准：

claude mcp add --help

只有服务商明确提供 SSE 时，才改成：

claude mcp add --transport sse legacy-mcp https://example.com/sse

我之前把 /sse 地址硬配成 http，终端连上后马上断。看起来很像 OAuth 挂了，其实授权流程压根没启动，挺烦人的。

验证端点和 OAuth 元数据

先用 curl 看 MCP 地址返回什么：

curl -i https://example.com/mcp

返回 401 不一定有问题。它可能说明端点存在，只是要求认证。要是返回网站 HTML、404 或 405，先查路径和 transport。

接着探测 OAuth 服务器元数据。具体位置由服务端声明，下面是常见标准路径，不保证每家都一样：

curl -i https://example.com/.well-known/oauth-authorization-server

部分实现使用受保护资源元数据：

curl -i https://example.com/.well-known/oauth-protected-resource

重点看 authorization_endpoint、token_endpoint、支持的 scope 和资源端点指向。

MCP 域名和授权域名不同很正常，但两边必须能通过元数据关联起来。

查回调端口有没有被占

OAuth 发起后，看浏览器地址栏里的 redirect_uri。假设它是：

http://127.0.0.1:43127/callback

macOS 或 Linux 检查端口：

lsof -nP -iTCP:43127 -sTCP:LISTEN

没有 lsof 可以用：

ss -lntp | grep 43127

Windows PowerShell 使用：

Get-NetTCPConnection -LocalPort 43127

正常情况下，监听这个端口的应该是当前 Claude Code 相关进程。要是端口被另一个 Node.js 进程占了，先确认 PID：

ps -fp <PID>

别看到 Node.js 就直接 kill -9，那很可能是你另一个开发服务。确认进程身份后正常结束，再重新发起授权。

如果浏览器和 Claude Code 不在同一台机器，localhost 指向的对象也不一样。浏览器可能把授权码发给自己的本机，而 Claude Code 还在远端等。俩人隔空对线，谁也收不到。

这种情况应优先使用工具或服务商明确支持的设备授权、固定回调地址或端口转发。我也没法说哪种方案对所有远程环境都最好，因为不同 OAuth 服务对动态端口的支持差异确实很大。

逐字符核对 redirect URI

下面两个地址在 OAuth 看来不是一回事：

http://localhost:43127/callback
http://127.0.0.1:43127/callback

这两个也不同：

http://localhost:43127/callback
http://localhost:43127/callback/

核对时别只盯着域名：

字段	常见差异
Scheme	http 与 https
Host	localhost 与 127.0.0.1
Port	固定端口与动态端口
Path	/callback 与其他路径
尾斜杠	/callback 与 /callback/
编码	原始地址与 URL 编码后的地址

如果服务端只登记了固定 URI，而 Claude Code 每次生成动态端口，授权肯定会失败。应该修改 OAuth 客户端登记，或者采用服务端支持的回调模式，别手改浏览器地址。

手改可能破坏 state、PKCE verifier 或当前授权会话。

查令牌到底存到哪里

Claude Code 的 OAuth Token 不该直接提交到项目 .mcp.json。项目配置通常只保留服务地址：

{
 "mcpServers": {
 "team-mcp": {"type": "http", "url": "https://example.com/mcp"}
 }
}

字段 schema 以本机版本为准。Client Secret、Access Token 和 Refresh Token 都别写进 Git 仓库。

令牌可能进入系统凭据库，也可能写进应用私有目录，具体取决于 Claude Code 版本和操作系统。与其照搬一个可能已经过期的路径，我更习惯在完成登录后的 10 分钟内查最近变化的文件：

find ~/.config ~/.cache ~/.local/share -type f -mmin -10 2>/dev/null

macOS 可以打开“钥匙串访问”，Linux 查看当前桌面环境的 Secret Service，Windows 查看“凭据管理器”。搜索服务名、MCP 域名或 Claude 相关条目，别把凭据内容贴进 Issue。

可以按下面的情况判断：

• 登录后完全没有新凭据：多半是回调没有抵达。
• 有 Access Token，没有 Refresh Token：过期后可能必须重新登录。
• Refresh Token 存在但持续 invalid_grant：可能已撤销、被轮换或重复使用。
• 退出终端就丢失：可能只写进了当前进程内存。

清理授权时，优先使用 /mcp 里的断开或重新认证操作。当前资料没有核实统一的清理命令，不建议直接 rm -rf 整个配置目录。这招很猛，也很容易把其他服务一起扬了。

处理刷新失败

下面是一条完整的典型错误样式，具体措辞可能随版本变化：

OAuth token refresh failed: invalid_grant
error_description: The refresh token is expired, revoked, malformed, or invalid

先检查系统时间：

date -u

Linux 还可以查看同步状态：

timedatectl status

时间偏差会影响令牌的 iat、nbf 和 exp 判断。时间没问题，再查 scope、audience、资源地址，以及 OAuth 客户端是否被服务端重新配置过。

有些服务采用 Refresh Token Rotation。每次刷新都会签发新的 Refresh Token，旧值立即失效。

如果两个 Claude Code 进程共用一份凭据，进程 A 刷新后，进程 B 再拿旧令牌刷新，就会收到 invalid_grant。这类坑测完我人傻了。看起来像随机掉线，其实是两个终端互相踢。

主流接入方式怎么配

Claude Code 原生远程 MCP

claude mcp add --transport http docs https://example.com/mcp
claude

然后通过 /mcp 完成 OAuth。这是本文主要使用的路径，也更适合交互式登录。

项目 .mcp.json

{
 "mcpServers": {
 "docs": {"type": "http", "url": "https://example.com/mcp"}
 }
}

它适合共享端点配置，不适合共享令牌。提交前务必运行 git diff --staged。

MCP 官方 SDK 探测

先建立最小项目：

npm init -y
npm i @modelcontextprotocol/sdk
npm pkg set type=module

创建 probe.js：

import {Client} from "@modelcontextprotocol/sdk/client/index.js";
import {StreamableHTTPClientTransport} from "@modelcontextprotocol/sdk/client/streamableHttp.js";
const c=new Client({name:"probe",version:"1.0.0"});
await c.connect(new StreamableHTTPClientTransport(new URL(process.env.MCP_URL)));
console.log(await c.listTools());

运行：

MCP_URL=https://example.com/mcp node probe.js

没有注入 OAuth provider 时，受保护端点返回 401 很正常。这个探针主要用来区分“端点或 transport 错误”和“Claude Code 的授权回调错误”，不是用来绕开 OAuth。

Cline 与 Zed

Cline、Zed 的配置界面和 schema 会随版本变化，但操作思路一样：在各自的 MCP 管理面板添加 https://example.com/mcp，transport 选 HTTP，再由工具端触发登录。

真正可迁移的核心配置只有这部分：

{
 "name": "docs",
 "type": "http",
 "url": "https://example.com/mcp"
}

如果工具不接受这段 JSON，别硬塞进设置文件。用它的 MCP UI 分别填写 name、type、url。

也别从 Claude Code 的系统凭据库里复制 Token 到另一个工具。每个客户端都应该独立完成 OAuth，并持有自己的 PKCE 状态。

OpenAI 兼容接口与聚合网关

这条路径是模型调用，不是 MCP OAuth。以 Python 为例：

from openai import OpenAI
client = OpenAI(api_key="your-key", base_url="https://api.ofox.io/v1")
print(client.models.list())

OpenRouter 与 ofox.io 都属于模型 API 方案；前者与后者的 Key 只能用于各自支持的模型请求，不能解决远程 MCP 的 redirect_uri_mismatch。在 Cline 等工具里，模型 Provider 和 MCP Servers 也是两块独立配置，别把 Base URL 填进 MCP URL，404 基本就这么来的。

不同场景怎么选

场景	选择	原因
个人终端、需要浏览器登录	Claude Code 原生 HTTP	OAuth 交互路径短
团队共享 MCP 地址	项目 .mcp.json	共享 URL，不共享令牌
怀疑 Claude Code 客户端有问题	官方 SDK 探针	能单独验证端点和 transport
Cline 或 Zed 中使用	各工具独立授权	避免复制令牌和 PKCE 状态
旧服务只提供事件流	SSE	仅在服务商明确要求时使用
SSH、容器、远程环境	设备授权或受支持的端口转发	浏览器与 CLI 可能不在同一网络空间
同时配置模型与 MCP	分开配置两条链路	API Key 和 OAuth Token 用途不同

完整报错对照表

截至 2026 年 11 月 4 日，一手素材没有收录 Claude Code 官方固定报错原文。下表列的是排错时常见的错误样式，实际措辞可能不同。

现象或报错	常见原因	解法
MCP server returned HTTP 401 Unauthorized	未登录、Token 过期、scope 或 audience 错误	在 /mcp 重新认证，检查 OAuth 元数据
OAuth authorization failed: redirect_uri_mismatch	登记地址与实际地址不一致	逐字符核对协议、host、端口、路径
MCP connection failed: server returned HTTP 404 Not Found	URL 少了 /mcp，或填成网页地址	用 curl -i 检查真实端点
405 Method Not Allowed	transport 或请求方法不匹配	核对 HTTP 与 SSE 文档
OAuth token refresh failed: invalid_grant	Refresh Token 过期、撤销或轮换冲突	清理单个服务授权后重新登录
listen EADDRINUSE: address already in use 127.0.0.1:<port>	回调端口被其他进程占用	用 lsof、ss 或 PowerShell 找 PID
浏览器成功但终端持续等待	回调发到另一台机器，或终端已退出	保持原终端运行，检查 localhost 所在环境
重启后再次要求授权	凭据没持久化或系统凭据库不可用	检查凭据库权限与最近修改文件

端口占用的完整典型错误一般长这样：

Error: listen EADDRINUSE: address already in use 127.0.0.1:43127
 at Server.setupListenHandle [as _listen2] (node:net)
 code: 'EADDRINUSE'

看到它就别再点十遍授权按钮了。每点一次都可能生成一组新的 state 和 PKCE verifier。旧页面就算显示成功，也完成不了新会话。

常见问题 FAQ

1. Claude Code 配置远程 MCP 后，为什么没有自动弹出 OAuth 登录？

因为添加 URL 只完成了服务注册。启动 Claude Code 后执行 /mcp，选择对应服务并触发认证。

如果没有认证入口，检查远程端点是否真的声明了 OAuth 能力，再确认 transport 有没有选错。

2. 浏览器显示授权成功，Claude Code 为什么还是 401？

浏览器成功只说明授权服务器接受了登录，不代表回调已经被 Claude Code 收到。

检查发起授权的终端是否仍在运行、回调端口是否监听，以及浏览器和 CLI 是否位于同一台机器。

3. Claude Code 远程 MCP 应该选 HTTP 还是 SSE？

新服务优先选 http。只有服务商明确提供 SSE 端点时才用 sse。

碰到 404、405，或者连接后立即断开，都该回头核对 transport。

4. Claude Code 的 MCP OAuth Token 缓存在哪里？

目前没有适用于所有版本和系统的固定路径。它可能存放在系统凭据库，也可能位于应用私有目录。

建议通过系统凭据管理工具和最近修改文件定位，别盲删整个配置目录。

5. redirect_uri_mismatch 可以手动改浏览器地址解决吗？

不建议。手动修改可能破坏 state、PKCE challenge 和当前授权会话。

正确做法是让 OAuth 服务端登记的 URI 与客户端实际生成的 URI 完全一致。

6. 多个工具能共用同一个 OAuth Token 吗？

不建议。Claude Code、Cline 和 Zed 应该分别完成授权。

它们可能使用不同的 client ID、redirect URI、PKCE verifier 和缓存机制。强行复制 Token，还可能触发刷新令牌轮换冲突。

7. 删除 MCP 再添加，为什么还是刷新失败？

因为连接配置和凭据缓存可能是两套数据。删掉 URL，不一定会删掉系统凭据库里的旧 Refresh