Troubleshooting

Common setup checks

Confirm the configured server URL is https://api.languageweaver.com/mcp/v1.
Confirm npx is available and mcp-remote can be started, and that node --version reports 20.18.1 or later — see Prerequisites.
Confirm the selected client entry matches your authentication mode (interactive or service).
Confirm the configured authentication details are valid and current for the selected mode.

Where to find the logs

Claude Desktop writes a separate log file per configured MCP server, named after the entry's key in claude_desktop_config.json:

~/Library/Logs/Claude/mcp-server-<name>.log

For the examples in Setup, that is mcp-server-Language Weaver.log for the interactive entry and mcp-server-Language Weaver (service).log for the service entry.

This is the first place to look when the server does not appear in the tools menu, since startup failures — a missing node, an unresolved npx, a bad command path — are reported there and nowhere in the chat window.

Note

If you installed the .mcpb extension instead of configuring mcp-remote manually, the log lives at a different path — one file per installed extension name:

~/Library/Logs/Claude/lw-connector-<bundle>.log

(%APPDATA%\Claude\logs\ on Windows). Credentials are redacted from this log. Set LW_MCP_LOG_FILE=off in the extension's environment to disable it.

Connection-level errors

Failures that happen before a tool runs — while the client is authenticating to the MCP server — are returned as real HTTP responses, with a JSON body:

{
  "error": "unauthorized",
  "error_description": "Authentication required to access the MCP server"
}

Two statuses are returned. The difference matters because it decides whether your client starts an interactive login:

Status	`WWW-Authenticate`	What it means	What to do
`401`	Sent (`Bearer`)	The request carried no acceptable credentials, and interactive login is offered. `mcp-remote` treats this as a challenge and opens the browser.	For an interactive entry this is normal on first connection — complete the sign-in. For a service entry it means the credentials were not accepted; see the note below.
`403`	Not sent	The endpoint does not offer interactive login. No login is attempted and the request fails.	Configure a service entry with valid `Lw-Client-Id` and `Lw-Client-Secret`, or check them if you already have.

error distinguishes the causes of a 401:

`error`	Cause
`unauthorized`	No `Authorization` header was sent.
`invalid_token`	A token was sent but was rejected — expired, wrong issuer, or wrong audience.

Note

Invalid service credentials do not produce a distinct error. They are simply not accepted, the request continues as unauthenticated, and the server answers 401 — so a mistyped Lw-Client-Id or Lw-Client-Secret surfaces as an unexpected browser login prompt rather than a credentials error. If a service entry starts asking you to sign in, check the credentials first.

Health and discovery endpoints are unauthenticated, so reaching them proves the server is up but says nothing about your credentials. A connection error instead of a 401/403 means the server URL is wrong or the server is not running.

Tool error structure

Once the client is connected, a tool failure is not returned as a transport-level HTTP error. The MCP request itself succeeds and the tool result carries the failure, so the client stays connected and can act on the detail.

Every failed tool call returns:

isError set to true — this is what marks the result as a failure;
the message repeated as text content, so clients that only render text still show something useful to the user;
structured content with the fields below.

{
  "code": "MCP_ERROR_CODE",
  "message": "Human-readable message",
  "retryable": false,
  "traceId": "..."
}

Field	Type	Description
`code`	string	One of the `McpErrorCode` values listed below. Use this, not the message text, to branch on.
`message`	string	Human-readable explanation. Also returned as the result's text content.
`retryable`	boolean	`true` when the same call may succeed if repeated after a short delay. `false` means the request must change first.
`traceId`	string	Identifier for this tool call, also written to the server logs.

MCP error codes

The server maps failures to the following McpErrorCode values. Branch on code, never on the message text.

Code	Retryable	Meaning / action
`VALIDATION_ERROR`	no	Invalid tool input. Fix arguments and retry.
`GROUP_SELECTION_REQUIRED`	no	Caller belongs to multiple groups. Re-run with a valid `groupId`.
`GROUP_SELECTION_INVALID`	no	Provided `groupId` is not allowed for caller. Choose a listed group.
`INVALID_LANGUAGE_PAIR`	no	Source/target/model not available for selected group.
`AUTHENTICATION_ERROR`	no	Authentication to Language Weaver failed. Refresh token or credentials.
`AUTHORIZATION_ERROR`	no	Caller is authenticated but not authorized for this action.
`UPSTREAM_UNAVAILABLE`	yes	Language Weaver service temporarily unavailable.
`UPSTREAM_ERROR`	no	Upstream returned an error while processing request.
`NETWORK_ERROR`	yes	Network failure reaching upstream service.
`INTERNAL_ERROR`	no	Unexpected server error.

The first four codes return a specific, actionable message naming what to change. The rest return a fixed generic message, so use code and traceId rather than parsing the text.

Tool-specific issues

A language code is rejected: fetch exact Language Weaver code via lw_get_language_codes.
Translation fails for otherwise valid languages: check group-specific language pair availability via lw_get_account_language_pairs.
lw_get_translation_result fails: request is not DONE yet; keep polling status.