Troubleshooting

MCP-layer errors follow the JSON-RPC error shape:

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

HTTP status + error.code + error.message together form the signal. This page classifies common symptoms.

401 Missing or malformed Authorization header

Trigger: no Authorization header, or the format isn't Bearer <token>.

Fix:

• Verify headers.Authorization in your mcp.json
• The value must be Bearer + space + token — mind the space
• Some clients lowercase headers; this service is case-insensitive but the header must be present

401 Invalid token

The same message can have two root causes — the server deliberately doesn't distinguish them to avoid leaking security information:

Cause A: token typo / expired / revoked

Fix:

• Console → Open Platform → AI Agent Access card; check the first 12-char prefix of the current token matches the token in your request header
• Prefix mismatch → token was rotated; update mcp.json with the new one
• Card shows "not generated" → token was revoked; generate a fresh one

Cause B: project doesn't have Open Platform enabled (missing App Key / App Secret)

This is the most common UX trap: you can generate an MCP Token on a project without an App Key — token generation looks successful, but every call returns 401.

Fix:

• Console → project → Open Platform. Above the AI Agent Access card there should be an App Key + App Secret display area
• If it shows "not generated" → click Generate App Secret (App Key is generated at the same time)
• You don't need to regenerate the MCP Token — the existing token starts working immediately

If both Cause A and Cause B are ruled out and the token prefix still matches, contact the platform maintainer.

422 Project has no configured source language

Trigger: any tool that requires a source language, e.g. loxily_create_task, loxily_create_terms, loxily_supplement_translate.

Fix:

• Console → project → Translation Language Settings; confirm the source language is configured (e.g. "Simplified Chinese")
• If it looks configured but still 422 → contact the platform maintainer; usually the backend service is behind the console and needs to be upgraded

422 target_languages contains unsupported language(s)

Trigger: create_task / supplement_translate passes target_languages containing languages the project hasn't enabled.

Fix: call loxily_list_languages first; use the returned target_languages as your allowlist.

HTTP 200 but result.isError=true

MCP protocol convention: downstream business errors (Open Platform 4xx / 5xx) are NOT surfaced as HTTP-layer errors. They're wrapped inside the tool result as isError: true + content[0].text. This lets the agent decide whether to retry or show the message to the user.

Diagnosis steps:

1. Check result.isError — must be true for a business error
2. Read result.content[0].text — contains the HTTP status, error code, and trace_id
3. Use trace_id to look up the full request/response/callback timeline in console → Open Platform → Call Logs tab

Transport layer: SSE / 502 / connection reset

MCP Streamable HTTP uses SSE long-poll. If the client reports 502 Bad Gateway / connection reset:

• First GET https://mcp.loxily.com/health to check the service is alive (no auth required, 200 = healthy)
• The health response includes a revision field identifying the current deployment; include it when filing tickets
• If health is 200 but tools/call keeps dropping, it may be a client-side proxy / corporate firewall blocking SSE — try disabling the proxy to reproduce

Quick self-check script

Bring your token and run these 5 steps to validate the full pipeline:

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

# 1. health
curl -sS $BASE/health

# 2. initialize (get 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 should return 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 read-only smoke
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":{}}}'

For any failing step, jump to the section above. If none apply, provide the revision (from step 1) and trace_id (from the step 5 response) to the platform maintainer.