MCP troubleshooting

Diagnose tool discovery, authentication, organization access, arguments, and uncertain outcomes before retrying.

Use the symptom to choose the next check: a missing tool calls for inspecting the connection, while a rejected call needs its argument or permission error. Keep the tool name, non-secret inputs, response, and relevant resource or source revision. That evidence helps recover the intended work without repeating a write whose outcome is unknown.

The expected tools are missing #

Compare the configured endpoint with the inventory returned by the client. /mcp and /main expose the same authenticated tools; /account redirects to /main after authentication.

Look for members_listMemberships and engines_list and follow the first-read examples. Use the current tools/list response for exact names and schemas. An API endpoint's existence does not establish that MCP exposes it.

If only some tools are hidden, inspect the client's allowlist and approvals and enable only what the task needs. For a tool that should be present but is absent, retain the server/version and non-secret discovery output for a report.

GET returns 405 #

Configure Streamable HTTP at /mcp. After authentication, GET on /mcp or /main returns 405 with Allow: POST; the client sends MCP messages with POST. A missing or invalid token returns 401 before dispatch. An authenticated request to /account instead returns 308 to /main. These GET responses do not test whether a valid MCP POST connection works. Inspect the client's connection error after selecting the correct transport.

Authentication or organization is wrong #

For 401, check that the connection completed OAuth as the intended Lingo.dev user. The hosted server requires a valid user bearer token; a personal or service API key is not accepted in x-api-key or as the bearer value. Let the client refresh its authorization or reconnect through its account management. Keep tokens out of diagnostics.

Call members_listMemberships, choose the intended organization from data, and pass its ID in the next tool's organization field. For engines_list, that field is orgId. Choosing another organization in the same list does not require another OAuth authorization. Reconnect when the signed-in person is wrong; restarting alone can reuse the saved session.

If the membership appears under ssoRequired, sign in to Lingo.dev through that organization's identity provider and reconnect. If both data and ssoRequired are empty, complete organization setup at https://lingo.dev/orgs/start, then read memberships again. An unavailable organization can be absent, outside the user's memberships, or require SSO; do not treat every such response as an expired credential.

For a tool's permission or entitlement refusal, inspect the operation's requirements instead of repeatedly authenticating. Organization access and permission to perform a particular write are separate checks. Explain the missing authority without silently choosing a broader role or credential.

A tool says the organization's setup is unfinished #

The organization was created recently, and its creator has not finished setting it up in the web app: integrations, teammates, and the first engine. Org-level tools can be held until setup is finished; retrying or reauthorizing does not finish those steps. members_listMemberships remains available. Open the link in the message, https://lingo.dev/orgs/<orgId>, as the organization's creator, finish the steps the message names, then repeat the call. See Finish setting up a new organization.

The tool rejects arguments #

Compare the input with the exact schema returned by the connection. Current tool arguments are flat fields, with nested values kept where the schema declares them. Do not add invented body, params, or query wrappers. Supply the explicit organization field where required; it is not injected from the bearer. Optional intent describes the task. See Capabilities for the supported account operations.

Check what each ID identifies. members_remove.id is the membership ID from members_list; members_setRole.userId identifies that membership's user. A localization engine ID cannot substitute for a request-log ID. Copy opaque cursors or full-precision timestamp/ID pairs exactly instead of rebuilding them from displayed dates.

Preserve the schema's distinctions between omitted and null values, numbers and strings, arrays and single values. Check the connected tool's schema before applying a workaround to an argument error.

An account write or job has an uncertain outcome #

Read the relevant resource or job status before retrying. A network error can occur after the server accepted key creation, an invitation, a review decision, a suggestion, or a job. Establish whether the intended change exists rather than submitting it again automatically.

For submitted provisioning, read provisioningJobs_get with the saved job ID before deciding whether to retry. For other operations, inspect the saved resource and the connected tool's completion contract. Use the CLI or API reference for translation workflows.

Documentation or evidence is missing #

Search with localization_search, then pass a result's path to docs_fetch to read the full page. If the path fails, search again for the task and use a current result. The knowledge base uses a separate storage path from the file-backed website, so a website page may be absent or stale in that index. Check the current website reference before concluding that the capability is unavailable.

When reporting an unresolved MCP gap, include the attempted task, exact tool name, server version, and non-secret response. A report's acknowledgement does not promise a fix date.

For a quality inquiry, identify what is missing: source evidence, a completed evaluation, an applicable criterion, or a determinate answer. Those require different next steps. Measure explains how to report the evidence available without treating unanswered cases as passes.