> For the complete documentation index, see [llms.txt](https://docs.unitlab.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unitlab.ai/api-sdk-cli/mcp/troubleshooting.md). # MCP troubleshooting and FAQs Fix Unitlab MCP sign-in, permissions, uploads, stale annotation revisions, AI model runs, rate limits, and export issues. Start with the error's **Next:** sentence. Unitlab tools provide guidance for common failures, and operations that start background work return a `next_step` describing what to check. Your assistant can also use: * `get_help` with `error` set to the message it received. * `get_help` with `tool` set to the tool name for arguments, requirements, and common errors. * `diagnose` for the live connection, project, item, or task state. Example prompt: > Diagnose why this Unitlab task cannot be completed. Check the current stage, assignment, annotation validation, and connection permissions. Explain the blocker before making changes. ## Connection and sign-in | Symptom | What to check | | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | The assistant cannot find the server | Use `https://api.unitlab.ai/mcp` for hosted Unitlab. For a dedicated deployment, copy the address from its Connected assistants page. Use Streamable HTTP with OAuth. | | Sign-in never starts | Follow the client-specific setup guide. In Codex, try `codex mcp login unitlab`; in Gemini CLI, `/mcp auth unitlab`; in Claude Code, `/mcp`. | | No workspace is available | Sign in to the intended account, create or join a Unitlab workspace, then restart connection setup. | | The wrong workspace is connected | Reconnect and select the intended workspace on the consent screen. No tool changes the connection's workspace. | | The client does not offer custom MCP | Check the client's version, plan, and organization policy. The server cannot enable a client feature that the account does not offer. | | Authentication is refused after previously working | Check membership and connection status in Unitlab. A disconnected, removed, or deactivated member must restore eligibility and connect again. | An unauthenticated request to the MCP endpoint is expected to require authentication. Opening the endpoint in a browser is not a complete connection test. Ask the connected assistant to call `get_context`. See [Connect your AI assistant](https://docs.unitlab.ai/api-sdk-cli/mcp/connect-your-assistant). ## Access and visible tools ### “Connected with read-only access” Read tools continue to work, but writes are refused. Disconnect and reconnect with **Read and write** if changes are intended. Editing the permission switches alone does not raise the access level. ### “This connection does not include the permission” The required permission was disabled for this assistant. In **Settings → Connected assistants**, open your connection's **Edit permissions**, enable the needed permission, and save. The next call uses the change without reconnecting. ### “Your workspace role does not allow this” Your role lacks a required permission. The assistant cannot grant itself more access. Ask a workspace owner or authorized administrator to review your role, then check `get_context` again. ### The workspace is read-only or no seat is assigned Read `access.workspace_writable` and `access.seat_assigned` from `get_context`. An owner must resolve the workspace condition or assign a seat as appropriate. Repeated tool calls do not change these conditions. ### Some tools are missing Unitlab filters parts of the tool catalog according to effective permissions. Check the role, access level, and optional connection permission list. A tool can also be unavailable in an assistant whose client policy disables it. ### A project or item is “not found” An incorrect ID, an ID in another workspace, and an item hidden from your role can produce the same response. Retrieve IDs from fresh `list_projects`, `list_items`, or `list_tasks` results. Keep `task_id`, `datasource_id`, `group_id`, and `assignment_id` distinct. If an item was just uploaded, it may still be processing. If a non-manager completed a task, the task may have left the stages they can access. See [Authentication and permissions](https://docs.unitlab.ai/api-sdk-cli/mcp/authentication-and-permissions). ## Uploads and processing | Symptom | Resolution | | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | The assistant can see a filename but cannot upload it | Confirm the client can read the actual file bytes and send HTTP file bodies. Otherwise upload in Unitlab or use existing library assets. | | The transfer URL or token is refused | Check the expiry and use the URL exactly as returned. Resume or restart according to `get_help` for `prepare_upload`; do not substitute another project's URL. | | Upload is incomplete | Check whether the mode requires `complete_upload`. Multipart uploads need every part number and ETag; LiDAR folders need completion after all files; medical form sessions need completion after the last file. | | Item exists but cannot be opened | Poll `get_upload_status`. Processing must finish; geospatial/pathology tiled status must also be ready. | | CSV has no usable data type yet | Resolve the required CSV configuration and choose tabular or time-series interpretation as appropriate. | | File is too large or unsupported | Read the server's message and the current upload guide. Supply the exact `size_bytes` when preparing the transfer. | | Processing failed | Read the processing error. Correct file content, structure, or configuration before retrying. | Large imagery and scenes can take longer than an ordinary image batch. Poll every few seconds rather than in a tight loop. Ask `get_help` for `upload-files` or `upload-a-lidar-scene` for the current transfer and structure rules. ## Annotation and task state ### A save reports a stale revision Another change was saved after the revision you read. Call `get_annotations` again, review the current objects, and reconcile the proposed update. Retry using the latest `revision` as `expected_revision`. Do not silently replace another annotator's work. ### A save succeeds but lists validation problems The update was stored, but required properties or other annotation rules remain unresolved. Use the schema and `problems` to correct them, then validate again. A successful save alone does not mean the task is ready for export or review. ### The task cannot be claimed Read `get_task` to check the stage, assignee, and `can_claim`. Someone else may hold it or your role may not be eligible. A manager with the required permission can release or reassign work when appropriate. ### The task will not advance Saving labels does not move a task. Read the current `actions` from `get_task` and use `perform_task_action` with an available action and the current `expected_stage_id`. The workflow determines the destination. ### Labels appear in the wrong place Check the coordinate metadata from `read_content`. Convert resized or cropped preview coordinates with `origin` and `scale`. Use zero-based video frames and medical slices, one-based PDF page numbers, and the schema's units. LiDAR geometry uses scene coordinates in metres rather than camera pixels. ### A Consensus or reference copy is missing Use its returned `assignment_id` together with the correct `datasource_id`. Private copies cannot be read as ordinary project items without the relevant context. Take the values from the current Consensus, reference, or benchmark result. ### Some objects or items are missing from the response Check pagination and continuation. Long responses can summarize or omit geometry while still reporting the full stored count. Use smaller image regions or continue through the remaining pages before concluding that data is missing. ## AI tools and model runs ### An AI tool does not support the item Check the modality and class type. Per-item segmentation, detection, and Find Similar support images, video, axial medical slices, geospatial, and pathology. They do not perform point-cloud detection. Video and medical operations require the relevant frame or slice. Smart and geometric refinement have different support. Tracking needs an existing supported track and starting keyframe. Ask `get_help` for the exact tool. ### No objects were detected A completed detection with no objects can be a valid result. Check the class, text prompt, threshold, image region, and object visibility. On very large imagery, inspect smaller regions. Do not report zero detections as proof that no target object exists. ### AI inference quota is exhausted The tool cannot raise the workspace quota. Check the workspace plan and usage. Find Similar and geometric refinement do not consume AI inference quota, but only use them when they fit the requested operation. ### A model service is unavailable For a transient service failure, wait briefly and retry once. If it fails again, report the tool and error instead of repeatedly consuming requests. Correct modality, class, and input errors rather than retrying unchanged calls. ### A Model stage is queued or processing Read `get_model_run`, including progress and notes. Poll the same run. `start_model_run` is not a way to accelerate a queued or running task. If the model service is temporarily unreachable, the run can remain queued or retry automatically according to its status. ### A failed model run cannot be started Read `at_model_stage` and `can_start`. A task that has already left the Model stage cannot be retried there by `start_model_run`. Inspect its current workflow and preview moving it back with `move_tasks` if another run is intended. ### Model configuration cannot be changed A stage may be locked while tasks are in it. Read the workflow and the error's guidance. Preview the impact before moving tasks or changing the graph, because entering a Model stage starts runs. ### Reference examples are not being used Check `get_references`. Example objects must be drawn, approved, and published. `needs_update` means the stage still uses the previous published examples until they are republished. An empty or unpublished example is not a usable reference. ### Cancellation is still pending A background model run must confirm it stopped before a new run can start. Continue checking `get_model_run`. Use the current `run_id` for cancellation; synchronous runs have no cancelable background ID. Imported annotations remain after cancellation. See [AI and model workflows](https://docs.unitlab.ai/api-sdk-cli/mcp/workflows). ## Releases and downloads | Symptom | Resolution | | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | A release is pending or exporting | Poll `get_release`; do not create another export for the project. | | A release failed | Read its error, correct the cause, then use `retry_release`. | | No annotated data can be exported | Check active classes, archived items, and annotation validation problems. | | Export has fewer items than expected | Compare release item counts and selected filters. Check whether annotations meet export requirements. | | Export contains items not yet reviewed | Workflow stage is not an export filter. Confirm item selection and review completion before creating the release. | | A split is empty | Very small datasets may not have enough items to populate every split. | | Download link expired | Call `get_release_download` again for a fresh temporary link. | | Read-only connection cannot get a download link | The download is recorded, so this operation requires write access. | ## Rate limits and interrupted requests `get_context` returns the current connection rate limit and paging limits. When rate-limited, wait for the delay stated in the error, then retry. Use supported larger pages and batched reads rather than many tiny calls. If a write response is lost, do not assume nothing changed. Read the current project, annotation revision, task, upload, or release state first. If the tool supports idempotency, reuse the same key only for the identical intended action. A key reused with different arguments is refused. If Unitlab reports an internal fault, inspect the state before retrying once. If the error repeats, record the tool name, time, and non-sensitive error text for support. Do not include tokens or signed transfer URLs. ## Frequently asked questions ### Do I need an API key to use Unitlab MCP? No. The documented assistant connection uses OAuth sign-in. Unitlab API keys are a separate integration mechanism for SDK and API use. See [Connect your AI assistant](https://docs.unitlab.ai/api-sdk-cli/mcp/connect-your-assistant). ### Can one connection access all my workspaces? No. It uses the workspace selected during authorization. Reconnect to choose another workspace. See [Authentication and permissions](https://docs.unitlab.ai/api-sdk-cli/mcp/authentication-and-permissions#one-connection-one-workspace). ### Can my assistant upload a folder of images? Yes, if it can access the files and send their bytes. It can prepare a batch and transfer each image. If the client cannot upload, use Unitlab's web app or existing library assets. See [Upload an image folder and label it](https://docs.unitlab.ai/api-sdk-cli/mcp/workflows#upload-an-image-folder-and-label-it). ### Can it recognize every object in every image? The assistant can coordinate detection for the classes you request across a dataset, or set up a suitable workflow model. Results depend on the data, model, and settings. Review missed objects, false detections, and required properties. One per-item detection call has explicit instance and modality limits. ### Is Find Similar the same as reference-based batch auto-labeling? `find_similar_objects` searches within one item or frame using an example. Cross-item reference-based batch labeling uses a workflow Model stage with approved, published examples. See [Reference-based batch labeling](https://docs.unitlab.ai/api-sdk-cli/mcp/workflows#reference-based-batch-labeling). ### Does MCP support LiDAR and other modalities? The toolset supports twelve data families, with modality-specific content readers and annotation schemas. LiDAR includes 3D geometry, camera views, point painting, and supported camera-assisted tracking. AI detection and segmentation have narrower modality support. See [Multimodal data and coordinates](https://docs.unitlab.ai/api-sdk-cli/mcp/workflows#multimodal-data-and-coordinates). ### Does an AI preview change my data? Where `save=false` is supported, the tool returns a preview without storing the annotation. It can still require write access and consume inference quota. Tracking always saves. Read the specific tool's guidance. ### Are exports limited to approved tasks? No. Release eligibility uses the selected data, active classes, archive state, and valid saved annotations. Workflow stage is not an export filter. Complete your review and verify the intended selection before exporting. ### Where can I find the current tool arguments? Your client receives the server's typed input schemas. Ask the assistant to call `get_help` with the tool name for detailed guidance. The [tool reference](https://docs.unitlab.ai/api-sdk-cli/mcp/tools) lists all tools by purpose. For an overview of the integration, return to [Unitlab MCP](https://docs.unitlab.ai/api-sdk-cli/mcp) or visit the [Unitlab MCP product page](https://unitlab.ai/en/mcp).