MCP troubleshooting
401 Unauthorized
The server answers 401 with code unauthenticated and this header when the token is missing, wrong, expired or
revoked:
401 from /mcp
WWW-Authenticate: Bearer resource_metadata="https://lantfly.com/.well-known/oauth-protected-resource/mcp", scope="mcp"
| Situation | Fix |
|---|---|
| OAuth client keeps asking to sign in | Normal on first use: the 401 starts OAuth. If it loops, remove the server from the client and add it again. |
| OAuth worked, then stopped | Access tokens last 1 hour and refresh tokens 30 days. Changing your password, disconnecting the app, or leaving the organization ends the grant. Reconnect. |
| API token | Check the header is exactly Authorization: Bearer <token>, the token wasn't revoked or regenerated, and hasn't expired. |
| Token in the URL | ?token= must be on the MCP address itself, URL-encoded. |
| Client reports an OAuth error before the browser opens | The client may use a custom redirect scheme (such as app://), which Lantfly refuses. Use the client's HTTP/loopback option or an API token. |
403 Forbidden
| Code or message | Cause | Fix |
|---|---|---|
forbidden, X-Lantfly-Account-Revoked: 1 | You aren't a member of the account in X-Lantfly-Account. | Fix the organization ID, or ask to be invited again. |
forbidden with an OAuth connection | An OAuth connection acts for the one account you picked and ignores other accounts. | Connect the app again and pick the other organization. |
insufficient_permissions on a REST path | An OAuth token works only on the MCP server. | Use an API token for REST calls. |
insufficient_permissions, "A run token reaches only its own run…" | A run token was used. | Use an API token or OAuth. |
account_suspended (423) | The workspace is suspended. | Ask the owner or agency. |
| "Origin not allowed." | A browser-based client sent an Origin the server doesn't accept. | Use a desktop or server-side client. |
A tool is missing
The server lists only tools your connection may use. Check, in order:
- Read-only? Read-only connections have no
call-actor,abort-run, per-actor tools or listening write tools. Reconnect without Read-only, or use a full-access token. - Token permissions? A permission-limited token needs each tool's permission, for example
actors.runforcall-actororlistening.readfor listening tools. See Permissions. - Actor-limited token? It gets no listening tools, and sees only its actors.
- Organization role? Without Start runs there's no
call-actor; without View social listening there are no listening tools. - Per-actor tool? The actor must be in
?actors=(first 20 only), not deprecated, and visible to you. - Client cache? Some clients cache the tool list. Restart the client or reconnect the server.
A tool returns isError
Business refusals come back as a tool result with isError: true and a message, not as HTTP errors, so the assistant
can read and react. Common messages:
| Message starts with | Meaning | Fix |
|---|---|---|
| "This API token does not have the … permission." | Token permission missing. | Add the permission or use another token. |
| "This token is read-only…" | Write on a read-only connection. | Reconnect with write access. |
| "Your role in this organization does not allow this (…)" | Organization role. | Ask an owner or admin. |
| "Your role on this project does not allow this (…)" | Listening project role. | Call get-my-project-access; ask a manager for a higher role. |
| "Invalid input: …" | The actor input doesn't match its schema. | Read get-actor-details and fix the input. |
| "not-enough-usage-to-run-paid-actor", "billing-on-hold", "concurrent-runs-limit-exceeded" | Run refused by billing or plan limits. | Buy credit, upgrade, or wait for runs to finish. |
| "At most 3 runs can be started in one MCP request." | Too many call-actor calls in one batch. | Send the rest in a new request. |
| "… was not found." | Wrong ID, or not visible to this connection. | Use search-actors, list-runs or list-listening-projects to find the ID. |
| "The answer is too large (… KB)." | A listening API tool returned over 200 KB. | Lower per_page, or narrow dates and filters. |
An unknown tool name is a JSON-RPC error -32602, not a tool result.
Timeouts and waiting
- A tool call waits at most 120 seconds (
wait_secs), and all calls in one HTTP request share those 120 seconds. When the budget is spent, later calls return at once with the run ID. - A run that outlives the wait keeps running. Have the assistant call
get-runwithwait_secs, thenget-dataset-items. - "rate-limit-exceeded: too many requests of this account are waiting at once (5)": your account already has 5
waiting requests (MCP and Actor Standby together). Retry shortly, or call with
wait_secs: 0and poll withget-run. - If your client gives up before 120 seconds, set a lower
wait_secs(for example 50) and poll, or raise the client's request timeout. - Tool calls count toward the API request budget. See Rate limits.
Protocol errors
| Answer | Cause |
|---|---|
405 on GET or DELETE | The server doesn't open server-to-client streams or keep sessions. Use POST. Clients handle this automatically. |
400, "Unsupported MCP-Protocol-Version" | The client sent a protocol version the server doesn't know. Supported: 2025-06-18, 2025-03-26, 2024-11-05. |
400, -32700 | The body isn't valid JSON. |
400, -32600, "a batch may hold at most 10 messages" | Split the batch. |
Still stuck
Check Activity in the Console: requests to the MCP server are logged with the tools they called. Then contact support with the time of the request and the client you use.