> 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/quickstart.md). # MCP quickstart Connect an assistant, create a project from an image folder, label selected object classes, and review the results in Unitlab. This guide walks through an example conversation that creates an image annotation project from a folder. It describes what to ask and what the assistant should verify. The prompts do not run until you send them to a connected assistant. ## Before you begin You need: * A Unitlab account and membership in the workspace you want to use. * An assistant that supports remote MCP over Streamable HTTP and OAuth. * Read-and-write access and the workspace permissions required for project creation, data upload, classes, and annotation. * An image folder your assistant can read and transfer, or data already uploaded to Unitlab. The [Image annotation guide](https://docs.unitlab.ai/documentation/annotations/image-annotation) explains the corresponding visual workbench. The example uses a folder named `road-scenes` and the classes **Car**, **Person**, and **Bicycle**. Use your own folder, project name, and labeling rules. ## 1. Connect your assistant Follow the instructions for your client in [Connect your AI assistant](https://docs.unitlab.ai/api-sdk-cli/mcp/connect-your-assistant). The hosted server address is: ``` https://api.unitlab.ai/mcp ``` During Unitlab sign-in, select your workspace and **Read and write**. Review the permissions under **Customize**, then select **Allow**. If you only want to inspect existing data, **Read only** is sufficient for the read steps in this guide. ## 2. Verify the workspace Send: > Show which Unitlab workspace I am connected to, what access this connection has, and the projects I can see. The assistant should use `get_context` and `list_projects`. Check the workspace name before creating data. If the wrong workspace is connected, reconnect and select the correct one. `get_context` reports whether writes are allowed, the member's effective permissions, the data families, and current request limits. A successful connection does not automatically grant permission to create or annotate a project. ## 3. Describe the project and object classes Attach or otherwise provide access to your image folder, then send: > Create a project named Road scenes from this folder. Use bounding boxes for Car, Person, and Bicycle. Upload all images, then detect those classes across the dataset. Keep the results available for my review. For a more precise task, add your labeling rules. For example: > Label visible cars, people, and bicycles. Use a separate box for each object. Do not label traffic signs or motorcycles. Tell me when an image is ambiguous or a detection needs review. The assistant should check for an existing matching project before creating a duplicate. A new project is created with `create_project`, and its class definitions are added with `create_ontology`. Class names become integer class values that annotation tools use internally. Projects begin with a default workflow. If an existing project has a Model stage, uploading data may start model runs immediately. The assistant should inspect the workflow before adding data and explain the expected runs. ## 4. Upload the folder For local files, the assistant first requests an upload destination with `prepare_upload`. It then transfers the bytes using the returned URL and instructions. For an ordinary image batch in form mode, there is one file upload request per image. Preparing the batch with `file_count` allows those files to share the prepared upload session. `get_upload_status` and `list_items` let the assistant verify what arrived. Ask for a clear result: > Confirm how many files uploaded successfully. List any files that failed or are still processing before labeling them. A folder attachment in a chat client does not guarantee that the client can send the files to Unitlab. If the assistant lacks file-transfer capability, upload the folder through Unitlab first, then send: > Use the images already in my Road scenes project. Check the classes and prepare the dataset for labeling. You can also reuse workspace library assets with `list_assets` and `attach_data`. See [Uploads and reusable data](https://docs.unitlab.ai/api-sdk-cli/mcp/workflows#uploads-and-reusable-data). ## 5. Create the first labels For each ready image, the assistant can inspect the content, read the current annotation revision, and call `detect_objects` for the requested class. It repeats this for the other classes and images as needed. The tool searches for **one class on one item per call**. The assistant coordinates the dataset-wide sequence. A separate workflow Model stage can perform automatic batch pre-labeling; it is described in [Workflows and automation](https://docs.unitlab.ai/api-sdk-cli/mcp/workflows#batch-auto-labeling-with-a-model-stage). Useful follow-up prompts include: > Start with a few representative images. Show me the saved detections and any validation problems before continuing. > Continue across the remaining images with the same classes and labeling rules. Report images with no detections or results that need attention. AI labeling is a starting point. Results depend on the imagery, model, prompts, thresholds, and object size. The per-item detection tool defaults to up to 100 instances per call and supports a configured maximum of 500. Crowded or very large imagery may need focused regions or a suitable workflow model. ## 6. Review the saved result Send: > Show several labeled examples from Road scenes. Check for missed cars, people, or bicycles, duplicate boxes, and required properties that are still empty. The assistant can use `read_content` with annotations displayed, inspect `get_annotations`, and validate changes. Open the project in Unitlab to review and correct labels visually. Saving labels and submitting a task are separate actions. Ask explicitly when you want work to move forward: > After the labels are checked, show which workflow actions are available. Submit the selected completed tasks for review. The assistant reads the available actions from `get_task` and uses `perform_task_action` when authorized. A saved annotation can still contain validation problems, so resolve these before handoff where possible. ## 7. Export when the dataset is ready After your review process, send: > Create a YOLOv8 release of Road scenes with an 80% training, 10% validation, and 10% test split. Show the export status and provide the download link when it is ready. The assistant uses `create_release`, waits with `get_release`, and retrieves a temporary link with `get_release_download`. It should reuse an in-progress release instead of starting another export. Release eligibility depends on valid saved annotations and active classes. Workflow stage is not an automatic export filter, so verify the intended items before exporting. See [Releases and exports](https://docs.unitlab.ai/api-sdk-cli/mcp/workflows#releases-and-exports). ## Continue * [Explore all MCP tools](https://docs.unitlab.ai/api-sdk-cli/mcp/tools). * [Configure batch auto-labeling and review workflows](https://docs.unitlab.ai/api-sdk-cli/mcp/workflows). * [Understand permissions and connection management](https://docs.unitlab.ai/api-sdk-cli/mcp/authentication-and-permissions). * [Resolve a blocked upload or task](https://docs.unitlab.ai/api-sdk-cli/mcp/troubleshooting).