> 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/authentication-and-permissions.md).

# MCP authentication and permissions

Understand OAuth, workspace scope, read and write access, role permissions, connection controls, and revocation in Unitlab MCP.

A Unitlab MCP connection acts as the member who authorizes it, in one selected workspace. It does not create an independent administrator account. Unitlab checks access when each tool is called.

## How authentication works

Your assistant opens the Unitlab OAuth sign-in flow. After sign-in, you select a workspace and approve the connection. The client receives tokens for the Unitlab MCP resource and uses them to call the remote server.

The standard client setup does not require a Unitlab API key. OAuth uses authorization-code and refresh-token grants with PKCE. Clients discover the authorization server from the MCP resource's public metadata.

| Scope           | Purpose                                                           |
| --------------- | ----------------------------------------------------------------- |
| `unitlab:read`  | Required for the connection and read operations.                  |
| `unitlab:write` | Required in addition to read for operations designated as writes. |

The protected-resource discovery document advertises the required read scope. Both scopes are advertised by the authorization server. Writes are checked per tool, so read-only clients can still connect and use read tools.

## Three controls determine what the assistant can do

An operation must be allowed by all of these controls:

1. **Your current workspace role.** The assistant cannot exceed the rights of the member who connected it.
2. **The connection's access level.** Read-only connections cannot perform write-designated operations.
3. **The connection's permission list.** Permissions disabled in **Customize** further restrict the assistant.

Writes also require a writable workspace and an assigned seat when the workspace uses seat-based access.

Ask your assistant:

> Show my effective Unitlab permissions and explain whether this connection can make changes.

It can use `get_context` to read `permissions` and the `access` flags. The role's name alone is not enough to decide what is allowed.

## Read only and Read and write

Choose the access level on the consent screen:

* **Read only** lets the assistant use permitted read tools to inspect projects, content, schemas, annotations, and other available information.
* **Read and write** also allows write-designated tools, within your role and connection permissions.

Read and write is preselected in the current consent screen. Review the selection before approving.

Some operations that look like previews are still write-designated. For example, an AI preview can consume inference quota and requires write access. `get_release_download` also requires write access because the download is recorded. In contrast, `validate_annotations` can check a proposed save without storing it.

See the **Access** column in the [tool reference](https://docs.unitlab.ai/api-sdk-cli/mcp/tools).

## Customize the connection's permissions

Expand **Customize** during authorization to disable permissions you do not want the assistant to use. Unitlab offers only permissions available to your current role.

If you leave every permission enabled, the connection follows your role, including permissions that role gains later. If you disable a permission, the stored list remains restricted until you edit it. A restricted list never preserves a permission that your role loses.

The list controls permission codes, which can apply to several tools. It is not a switch for every individual tool. Tool visibility can also change with your effective access, so two members may see different catalogs.

Common permissions include:

| Permission                                  | Typical use                                                          |
| ------------------------------------------- | -------------------------------------------------------------------- |
| `manage_projects`                           | Create and manage projects.                                          |
| `manage_data`                               | Upload and manage data.                                              |
| `view_ontology`                             | Read classes and properties.                                         |
| `manage_classes`                            | Create or change the ontology.                                       |
| `view_instructions` / `manage_instructions` | Read labeling instructions; management permission also allows edits. |
| `view_labeling_interface`                   | Open annotation content and use eligible AI tools.                   |
| `create_labels`                             | Save annotations and act on annotation tasks.                        |
| `manage_workflows`                          | Configure workflow stages.                                           |
| `manage_releases`                           | Create and retry releases.                                           |
| `manage_ai_models`                          | Register and manage workspace models.                                |
| `manage_workspace_settings`                 | Review workspace-wide assistant connections and applicable settings. |

Each tool can have additional state or visibility requirements. Ask `get_help` for the specific tool rather than assuming a permission code alone guarantees access.

## One connection, one workspace

The workspace is selected during authorization. Every tool call stays within that workspace, and no MCP tool switches the connection to another workspace.

To work elsewhere, reconnect and choose the other workspace. When the consent page reports an existing connection for the assistant, approving the new one replaces that existing workspace connection.

Project visibility also follows your role. Built-in member, annotator, and reviewer roles see projects and tasks available through their workflow stages. Owner, manager, and custom-role visibility can be broader, while operation-specific permissions still apply.

A “not found” response can mean the ID is incorrect, belongs to another workspace, or is not visible to your role. Use fresh results from `list_projects`, `list_items`, or `list_tasks`.

## Edit permissions after connecting

1. Open **Settings → Connected assistants**.
2. Find your assistant and open **Assistant actions**.
3. Select **Edit permissions**.
4. Change the switches and select **Save**.

The change applies to the assistant's next call without reconnecting. Only the member who owns a connection can edit its permission list. Workspace administrators who can review other members' connections can disconnect them, but do not edit their chosen permission lists.

The edit dialog does not change the workspace or access level. To move from Read only to Read and write, reconnect and approve the new access level.

## Disconnect and membership changes

Choose **Disconnect** from the assistant's actions menu and confirm. The connection and its tokens are revoked. Work already saved in Unitlab remains saved.

| Change                                     | Effect                                                                                                   |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| Role permissions change                    | The next call uses the new role permissions, still limited by the connection's access and optional list. |
| A permission is disabled on the connection | The next call loses that permission.                                                                     |
| Member is removed or deactivated           | The connection is revoked. Reactivation requires a new connection.                                       |
| Seat is removed                            | Reads can continue, but writes are refused.                                                              |
| Workspace becomes read-only                | Reads can continue, but writes are refused.                                                              |
| Account or workspace becomes unavailable   | Calls are refused; restore eligibility and reconnect as needed.                                          |

## Data handling

The assistant can receive the content it is authorized to request, such as images, text, labels, and metadata. Consider the data-handling policies of the assistant client you choose. This connection does not by itself establish that client's retention or training policies.

Signed upload URLs, access tokens, and temporary download links are credentials. Use them only for their intended transfer and avoid including them in shared prompts or public documentation. Creating an API key through a tool is a separate administrative operation; it is not necessary for MCP authentication.

Text and media read from an item are dataset content. They should not override the member's instructions to the assistant.

## When access is refused

Start with `get_context` or `diagnose`. A refusal may come from the connection, the role, the permission list, the workspace, the seat, or the task's current state. Repeating the same refused call does not increase access.

See [Troubleshooting](https://docs.unitlab.ai/api-sdk-cli/mcp/troubleshooting#access-and-visible-tools) for the next step for each case.