疑难排查

MCP 层错误统一走 JSON-RPC 结构：

json

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32001,
    "message": "..."
  },
  "id": null
}

HTTP 状态码 + error.code + error.message 一起构成错误信号。本页按现象分类给定位方向。

401 Missing or malformed Authorization header

触发：请求没带 Authorization header，或格式不是 Bearer <token>。

排查：

检查 mcp.json 里 headers.Authorization 字段是否拼写正确
值必须是 Bearer + 空格 + token，别漏空格
一些 MCP 客户端会把 header 转小写，本服务对大小写不敏感，但必须存在该 header

401 Invalid token

同一个错误消息背后可能有两种成因（服务端出于安全考虑不区分泄露具体原因）：

成因 A：Token 打错 / 过期 / 已 revoke

排查：

控制台"开放平台" → AI Agent 接入，看当前 token 的前 12 字符前缀是否与你请求头里的 token 前缀匹配
若前缀对不上 → token 被 rotate 过，重新在 mcp.json 里填新 token
若"AI Agent 接入"卡片显示"尚未生成" → token 被 revoke，重新生成

成因 B：项目未启用开放平台（缺 App Key / App Secret）

这是最常见的 UX 陷阱：可以在没有 App Key 的项目上生成 MCP Token，token 生成看似成功、但用起来必 401。

排查：

打开控制台 → 项目 → 开放平台，AI Agent 接入卡片上方应该有 App Key + App Secret 展示区
若显示"尚未生成" → 点 生成 App Secret（App Key 会同时生成）
不需要重新生成 MCP Token，同一个 token 立即生效

若成因 A / B 都已排除，token 前缀也对得上，仍持续 401 —— 请联系平台维护者。

422 Project has no configured source language

触发：调用 loxily_create_task / loxily_create_terms / loxily_supplement_translate 等需要源语言的接口。

排查：

控制台 → 项目 → 翻译语言设置，确认已配置源语言（"中文(大陆)"、"简体中文"等等）
若显示已配置但仍 422 → 联系平台维护者，通常是后端服务版本落后于控制台，需要升级

422 target_languages contains unsupported language(s)

触发：create_task / supplement_translate 传的 target_languages 里包含项目未启用的语言。

排查：先调 loxily_list_languages，用返回的 target_languages 作为白名单。

请求 200 但 `result.isError=true`

MCP 协议约定：下游业务错误（Open Platform 返回的 4xx / 5xx）不作为 HTTP 层错误，而是包装到 tool 的 result 里以 isError: true + content[0].text 形式返回。这样 Agent 可以自己决定是重试还是把错误消息展示给用户。

判断步骤：

读 result.isError — 是 true 才是业务错误
读 result.content[0].text — 里面有 HTTP status + error code + trace_id
用 trace_id 去控制台"开放平台" → 调用日志 Tab 反查完整请求/响应/回调时间线

连接层：SSE / 502 / connection reset

MCP Streamable HTTP 走 SSE 长连接。若客户端报 502 Bad Gateway / connection reset：

先 GET https://mcp.loxily.com/health 看服务是否活着（无鉴权，返回 200 即正常）
Health 响应里有 revision 字段用于识别当前部署版本，提工单时请附上这个字段
若 health 200 但 tools/call 频繁断线，可能是客户端 proxy / 企业防火墙拦截了 SSE，尝试临时关闭 proxy 复现

快速自检脚本

带上你的 token，跑一遍下面 5 步确认整条链路：

bash

export TOKEN='lox_mcp_YOUR_TOKEN'
BASE=https://mcp.loxily.com

# 1. health
curl -sS $BASE/health

# 2. initialize (拿 session)
curl -sS -D /tmp/h.txt -o /tmp/i.txt -X POST $BASE/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"self-check","version":"1.0"}}}'
SESSION=$(grep -i '^mcp-session-id:' /tmp/h.txt | awk '{print $2}' | tr -d '\r\n')
echo "session: $SESSION"

# 3. notifications/initialized
curl -sS -X POST $BASE/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Mcp-Session-Id: $SESSION" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

# 4. tools/list 数量应为 21
curl -sS -X POST $BASE/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Mcp-Session-Id: $SESSION" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | grep -o '"name":"loxily_[^"]*"' | sort -u | wc -l

# 5. loxily_list_languages 只读探活
curl -sS -X POST $BASE/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Mcp-Session-Id: $SESSION" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"loxily_list_languages","arguments":{}}}'

任何一步失败请对照本页上文分类定位。仍无法解决可提供：revision（步骤 1 里的字段）+ trace_id（步骤 5 响应里的字段）联系平台维护者。

疑难排查 ​

401 Missing or malformed Authorization header ​

401 Invalid token ​

成因 A：Token 打错 / 过期 / 已 revoke ​

成因 B：项目未启用开放平台（缺 App Key / App Secret） ​

422 Project has no configured source language ​

422 target_languages contains unsupported language(s) ​

请求 200 但 result.isError=true ​

连接层：SSE / 502 / connection reset ​

快速自检脚本 ​