SuperAnnotate MCP Server

The SuperAnnotate MCP Server is designed exclusively for use within pipelines. It enables you to connect an agent node directly to an event node without adding any intermediate custom action nodes, simplifying pipeline design and execution. To use it effectively, make sure the MCP tool is added to your agent, and be sure to provide detailed prompts and model instructions to your agent, so that your pipeline is executed as intended.

If the event payload doesn't contain the relevant project/folder/item/component IDs required to identify the correct parameters, please be sure to add either their name or ID in your prompt.

🚧
MCP Usage Risks
SuperAnnotate MCP tools can perform actions that modify items and their statuses; use them carefully and always validate your prompts and parameters. If needed, you can unselect specific tools from the MCP server configuration to explicitly exclude them and prevent the MCP from using those actions.

Supported Tools and Parameters

By default, tool calls never require approval.

Tool Name	Function Signature	Description
GET_PROJECT_METADATA	`project_id (int)` The project’s ID (required).	Retrieve a project’s details by project ID.
LIST_PROJECTS	`id__in: list[int]` Filter by a list of project IDs. `name: str` Filter by the project’s name. `name__in: list[str]` Filter by a list of project names. `status: Literal[“NotStarted”, “InProgress”, “Completed”, “OnHold”]` Filter by project statuses. `chunk_size (int)` Number of projects per page.	Search projects by filtering by name, ID and status.
GET_FOLDER_METADATA	`project_id (int)` The project’s ID (required). `folder_id (int)` The folder’s ID (required).	Retrieve a folder’s details by folder ID.
LIST_FOLDERS	`project_id (int)` Filter by project ID (required). `name (str)` Filter by the folder’s name. `status: str` Filter by folder’s status.	Search folders by filtering by project ID, folder name and status.
GET_ITEM_METADATA	`project_id (int)` The project’s ID (required). `item_id (int)` The item’s ID (required).	Retrieve an item’s details by item ID.
LIST_ITEMS	`project_id (int)` Filter by project ID (required). `folder_id (int)` Filter by folder ID (required). `id__in: list[int]` Filter by a list of item IDs. `name: str` Filter by item name. `name__in: list[str]` Filter by a list of item names. `annotation_status: int` Filter by an item’s annotation status. `annotation_status__in: list[int]` Filter by a list of item’s annotation statuses. `assignments__user_id: str` Filter by user ids assigned to an item. `assignments__user_id__in: list[str]` Filter by a list of user ids assigned to an item. `chunk_size (int)` Number of projects per page.	Search items by filtering by project ID, folder id, item id, item name, annotation status and user assignments.
SET_ITEM_STATUS	`project_id (int)` The project’s ID (required). `folder_id (int)` The folder’s ID (required). `item_id (int)` The item’s ID (required). `status: int \| str` The item’s status or ID (required).	Update the current item’s status.
GET_ITEM_ANNOTATIONS	`project_id (int)` The project’s ID (required). `folder_id (int)` The folder’s ID. `item_id (int)` The item's ID (required).	Fetches an item’s annotation’s JSON by item ID.
SET_ITEM_ANNOTATIONS	`project_id (int)` The project’s ID (required). `folder_id (int)` The folder’s ID. `item_id (int)` The item's ID (required). `annotation: dict` The item's annotation JSON (required).	Sets or updates an item’s annotations with a given payload.
list_workflow_statuses	`project_id (int)` The project’s ID (required). `workflow_id (int)` The workflow ID (required).	Search workflows to retrieve available item statuses.

Traces

Every time a model is called with the SuperAnnotate MCP Server tool, you can view its Traces in monitoring. In the Traces tab, we'll show the request and response payloads of all the tool calls made by the agent.

Connecting from outside SuperAnnotate

You can connect to the SuperAnnotate MCP Server from outside the platform using your SDK token as authentication, and the URL as https://mcp.superannotate.com/mcp.

{
  "mcpServers": {
    "Your_MCP_Label": {
      "type": "streamableHttp",
      "url": "https://mcp.superannotate.com/mcp",
      "headers": {
        "Authorization": "Bearer SA_SDK_TOKEN"
      }
    }
  }
}