故障排查

在下面找到你遇到的症状。每一节都说明错误的含义和处理方法。

我的 AI 应用连不上 Lune

如果连接彻底失败（超时，或提示「couldn't reach the server」）：

确认地址。服务器地址是 https://mcp.luneresearch.com。旧地址 https://mcp.luneresearch.com/mcp 和 https://mcp.luneresearch.com/v1/mcp 仍然可用。
确认你的网络能访问它。在终端里运行：
```
curl -sS -o /dev/null -w "%{http_code}\n" \
  https://mcp.luneresearch.com/.well-known/oauth-protected-resource
```
你应该看到 200。看到 5xx 说明 Lune 出了问题，过几分钟再试，一直不恢复就发邮件给客服。完全没有响应，则是你这一侧的网络或 DNS 有问题。
打开状态页面。它会从你的浏览器检测 MCP 服务器是否有响应，但不发布故障公告。

手动测试连接

用访问密钥列出工具。这次调用不计入请求数。

curl -sS https://mcp.luneresearch.com \
  -H "Authorization: Bearer lune_your_access_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

密钥有效时会以事件流返回工具列表：先是一行 event: message，再是一行 data:，里面就是 JSON-RPC 响应。其他结果的含义：

401：密钥错误或已经撤销，见下一节。
405：请求以 GET 发出。服务器只接受 POST。用浏览器打开这个地址会跳转到把 Lune 接入你的 AI 应用。
406：Accept 请求头少了两种类型中的一种。
415：Content-Type 请求头不是 application/json。
400：请求体不是合法的 JSON，或者 JSON-RPC 批量请求超过 50 条消息。修正 JSON，或把批量请求拆开发送。
403 并提示「origin not allowed」：请求来自网页。请从后端或原生应用调用服务器。

我遇到「401 unauthorized」或「invalid_token」

服务器没有接受这个凭证。

通过登录接入的应用（OAuth）。 应用会自己续期访问令牌。如果错误反复出现，说明登录已经结束：有人在凭证页面撤销了它、它闲置了 90 天，或者重复使用刷新令牌，Lune 撤销了整条令牌链。在应用里断开 Lune，再重新接入。
访问密钥。 密钥输错、已经撤销，或已过创建时设定的有效期。在凭证页面创建新密钥，替换旧的。成员只能撤销自己的密钥，所有者和管理员可以撤销团队里的任何密钥。
账户已暂停。 托管服务器对已暂停的账户返回的 401 和凭证无效时一样，本地 stdio 服务器则会返回一条说明账户已暂停的错误。如果重新接入后 401 依然存在，或者你看到了这条提示，请发邮件至 appeal@luneresearch.com。换新凭证没有用。

如果你在开发连接器

OAuth 发现从一次不带凭证的请求开始：

不带 Authorization 请求头向服务器发 POST。返回的 401 带有 WWW-Authenticate: Bearer resource_metadata="https://mcp.luneresearch.com/.well-known/oauth-protected-resource", scope="papers:read guidance:read account:read"。过期或无法验证的令牌会得到同样的响应头，并多出 error="invalid_token"，客户端应据此刷新令牌。
获取这份资源元数据。其中 authorization_servers 的值是 https://api.luneresearch.com。
获取 https://api.luneresearch.com/.well-known/oauth-authorization-server 拿到各端点，再按 auth.md 的说明注册、授权、换取令牌。

令牌端点拒绝表单编码的请求时，返回 400 和扁平的响应体 {"error": "...", "error_description": "..."}。请求体不是表单编码，或者缺少 grant_type 时，返回的则是 422 和 {"detail": [...]} 列表。注册时缺少 redirect_uris 返回 422，列表为空或含有 Lune 拒收的地址时返回 400。常见的 error 值：

`error`	原因	处理
`invalid_grant`	授权码已过期（有效期 10 分钟）、已经用过，或与 client ID、回调地址、PKCE verifier 不匹配；或刷新令牌已过期、已撤销，或重复使用过。	重新发起授权。
`invalid_target`	`resource` 与授权请求或刷新令牌上的值不一致。	每次请求都带 `resource=https://mcp.luneresearch.com`。
`invalid_redirect_uri`	注册时拒收回调地址：非回环主机上的 `http`、带片段，或不安全的 scheme。	改用 `https`、回环地址或私有 scheme。

授权请求的 redirect_uri 与已注册地址不完全一致时返回 400（http 回环地址的端口除外）；缺少 scope 时返回 422。客户端常见的错误见 auth.md。

我遇到「403」或缺少权限的错误

凭证本身有效，但缺少某个工具需要的权限。无论有哪些权限，工具列表都会显示全部工具，只是调用会失败。

OAuth。 服务器返回 403，WWW-Authenticate 响应头里的 error 是 insufficient_scope，scope 写明缺少的权限。在应用里断开 Lune，再重新接入。客户端应重新发起授权，并申请全部三个权限 papers:read guidance:read account:read，因为新的授权只包含请求里写明的权限。
访问密钥。 工具会返回一条写明缺少哪项权限的错误。创建一个包含该权限的密钥。各工具需要的权限见权限。

请求用完了，或者遇到「429」

这是两种不同的限制。

请求用完了。 每日额度和点数都不够这次调用时，工具返回错误，最后一行带有 http_status=402 和 quota_reason：

no_capacity：每日额度和点数都已用完。等到 UTC 午夜重置、购买点数，或在账单页面升级。点数包 $0.99 可换 300 次额外请求。
batch_too_large：批量工具请求的条目，既超过剩余的每日额度，也超过剩余点数。一次调用要么全用额度，要么全用点数，不会拆开支付。减少查询、Paper 或论断的数量后重试。
retry_now：调用进行期间额度恢复了。重试一次即可。

429。 这是防止脚本失控的每秒突发限流，与每日额度无关。等待 retry_after_seconds 给出的秒数，重试同一个调用，并让应用减少同时发出的调用。

每日额度和计费方式见套餐、请求与点数。

我的 AI 应用连上了，但工具不显示

重启 AI 应用。大多数客户端只在启动时获取工具列表。
网页 AI 应用：移除连接器再重新添加。
Claude Desktop：完全退出（只关窗口不够）再重新打开。

各类应用的更多提示见本地 AI Agent 和网页 AI 应用。

用量记到了错误的团队

通过登录接入的应用，用量始终记在你的个人团队名下。访问密钥的用量记在创建它的团队名下。想用共享团队的套餐，请在该团队下创建访问密钥，再用它连接。详见团队与访问密钥。

搜索结果看起来不对、缺失或过时

覆盖范围。 Lune 收录经同行评审的顶会。顶会页面和 list_conferences 工具列出主会论文已全部收录的顶会。Lune 仍在补全的顶会，其 Paper 也能搜到。其余会议的 Paper 不在文献库里。
时效性。 Lune 下一次抓取某个顶会时，才会加入它的新 Paper。抓取由人工发起，不按固定计划运行，所以最近发表的 Paper 可能要过几周才会出现。
措辞。 完整的自然语言查询（「methods for retrieval-augmented generation that reduce hallucination on long-form QA」）比关键词堆砌（「RAG hallucination」）找得更全。
顶会筛选。 Lune 不认识的 conference 名称会直接报错，而不是返回未经筛选的结果。venues 列表会保留认识的名称、丢掉其余的，一个都不认识时报错。名称有歧义时会返回候选名称供选择。可以让 Agent 先用 list_conferences 查准确的简称。

我还是卡住了

发邮件至 support@luneresearch.com，并附上：

你使用的 AI 应用（Claude、Cursor 等）
如果错误来自某次工具调用，写上工具名称
发生的时间（UTC）
完整的错误信息
这是新的配置，还是以前能正常工作的配置

我们通常当天回复。