Connection and authorization
Symptom
Your MCP client cannot add Landbase or cannot find the server.Check
Confirm that the server URL is exactly:Recovery
Remove any partially configured Landbase entry, add the exact URL again, and complete the browser authorization flow. For client-specific instructions, see Connect to Landbase MCP.Symptom
OAuth is rejected or the client reports that authorization failed.Check
Verify the server URL, confirm that the browser authorization completed, and check that the signed-in Landbase user has access to the intended account.Recovery
Disconnect and reconnect Landbase through the client’s MCP settings. Do not paste access tokens or authorization codes into chat, source control, or support messages.Symptom
The client says Landbase is connected, but no tools appear.Check
A configured server is not necessarily an authenticated server. Check the client’s MCP status and whether the tools are enabled for the current chat or agent mode.Recovery
Reconnect the server, complete OAuth again, start a new chat if necessary, and ask the client to calllist_accounts.
Accounts and results
Symptom
The assistant uses the wrong Landbase account or cannot determine the account.Check
Calllist_accounts. If multiple accounts are returned, identify the account the user selected and retain its string account_id.
Recovery
Pass the selectedaccount_id on every account-scoped read, write, confirmation, polling, recovery, and download call. Never infer account access from an account ID, dataset ID, or run ID.
Symptom
A search returns no results or results that do not match the request.Check
Inspect the search mode, filters, returned answer, available fields, and account context. Some filters require exact dictionary values such as supported country, industry, or seniority values.Recovery
Ask the assistant to show the search interpretation and available fields, then refine the query using those values. Do not start paid enrichment until the preview matches the intended audience.Running operations and retries
Symptom
A search returns a running handle.Check
Keep the opaque searchhandle and its session_id. A running response means the remote operation may still be active; it does not mean the search failed.
Recovery
Callget_search_result with the same handle, account_id, and an appropriate wait_seconds value. See Continue a search or workflow.
Symptom
A workflow or download is still running.Check
Keep the exactworkflow_run_id returned by the starting call and inspect its status. Terminal workflow states are SUCCEEDED, FAILED, and CANCELLED.
Recovery
Callget_workflow_run with the same run_id and account_id. When it succeeds, use its output_dataset_id for the next step. Do not assume the input dataset is the completed output.
Symptom
An MCP call timed out or the connection dropped after starting work.Check
Determine whether the response contained a search handle, session ID, agent run ID, or workflow run ID. A lost response does not prove that the remote operation did not start.Recovery
Recover and inspect the existing operation before retrying. Do not repeat a search, upload, paid workflow, publish call, or download call merely because its response was lost.Credits and confirmations
Symptom
A tool returnsneeds_confirmation.
Check
Read the returned credit quote, row count, or approval instruction. The tool has not necessarily started the paid or destructive operation yet.Recovery
Show the user what will happen and wait for explicit agreement. Repeat the same call withconfirm: true only after approval, keeping the same account_id and dataset or workflow identifiers.
Research-mode search uses a confirmation turn in the original session rather than a confirm boolean. Follow Limits and credits.
Symptom
The assistant wants to enrich, qualify, research, publish, download, delete, or cancel without showing the expected review step.Check
Confirm the requested operation, row count, credit behavior, destination, and whether the action is reversible.Recovery
Ask the assistant to preview or quote the operation first. Keep client-side tool approval controls enabled and do not treatconfirm: true as independent proof of human approval.
HTTP and service errors
Symptom
The server returns401 or 403.
Check
401 usually indicates missing or expired authentication. 403 can indicate that the user or workspace does not have MCP access or permission for the requested data or operation.
Recovery
Reconnect OAuth, verify the selected account and workspace, and confirm that the user has the required Landbase permissions. Do not work around a permission error by guessing another account.Symptom
The server returns402.
Check
The account may have insufficient credits or an operation may require a paid entitlement.Recovery
Tell the user which operation needs credits and how many rows or contacts it affects. Do not automatically retry.Symptom
The server returns429.
Check
The request or status read is rate-limited. Inspect any indicated retry delay.Recovery
Wait for the indicated delay and retry the same status read. Avoid starting a duplicate operation or polling more frequently.Symptom
The server returns503 during sign-in or token verification.
Check
Landbase may be temporarily unable to verify the authorization token.Recovery
Retry after the indicated delay. If the problem persists, reconnect OAuth and check Landbase service status before creating a new operation.Dataset and download errors
Symptom
The server returnsPUBLISH_REQUIRED or says the dataset cannot be downloaded directly.
Check
The dataset may be partitioned or may not have a published file in the requested format.Recovery
Callpublish_dataset, poll its workflow to SUCCEEDED, use the returned output_dataset_id, and then call get_download_url with the same account_id.