> 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/connect-your-assistant.md).

# Connect your AI assistant with MCP

Set up Unitlab MCP in Claude, Claude Code, ChatGPT, Codex, Cursor, Gemini CLI, VS Code, or another compatible client.

Unitlab provides a remote MCP server that your assistant connects to using OAuth. Use the client instructions below, then complete the shared Unitlab authorization flow.

## Server address

For hosted Unitlab:

```
https://api.unitlab.ai/mcp
```

For a dedicated deployment, open that Unitlab instance and copy the address in **Settings → Connected assistants → Connect assistant**. The server address is the API origin followed by `/mcp`. The web management route `/api/mcp/` is not the remote MCP server address.

Client menus, available features, and organization policies can differ by version and plan. Use the linked official guide if your client displays a different setup screen.

## Authorize the connection in Unitlab

After adding the server in your assistant:

1. Sign in to Unitlab when the browser opens.
2. Review the assistant name and the displayed return host.
3. Select the workspace the assistant should use.
4. Choose **Read only** or **Read and write**.
5. Expand **Customize** if you want to disable specific permissions.
6. Select **Allow** to return to the assistant.

If you do not have a workspace yet, create one in Unitlab and restart the connection from your assistant. Approving a replacement connection for the same assistant replaces its existing workspace connection.

You do not need a Unitlab API key or a manually created OAuth client ID for these standard flows.

## Claude Code

Run in your terminal:

```bash
claude mcp add --transport http unitlab https://api.unitlab.ai/mcp
```

Open Claude Code, run `/mcp`, select Unitlab, and complete sign-in.

The default configuration applies to the current project for your user. To make it available across projects, use:

```bash
claude mcp add --transport http --scope user unitlab https://api.unitlab.ai/mcp
```

[Official Claude Code MCP guide](https://code.claude.com/docs/en/mcp).

## Claude web and desktop

1. Open **Customize → Connectors**.
2. Select **+ Add → Add custom connector**.
3. Name the connector **Unitlab** and enter `https://api.unitlab.ai/mcp`.
4. Continue through the authentication settings and add the connector.
5. Connect your Unitlab account and complete the authorization steps above.

For Team and Enterprise, an authorized organization administrator may need to add the custom connector first under **Organization settings → Connectors**. Members then connect their own Unitlab accounts.

Remote web connectors must be able to reach your MCP endpoint, which matters for private deployments.

[Official Claude custom connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

## Codex

Run:

```bash
codex mcp add unitlab --url https://api.unitlab.ai/mcp
```

Complete the browser sign-in when prompted. If sign-in does not start, run:

```bash
codex mcp login unitlab
```

Return to Codex and ask it to check the connected Unitlab workspace.

[Official Codex MCP guide](https://developers.openai.com/codex/mcp).

## ChatGPT

1. Open [ChatGPT Plugins](https://chatgpt.com/plugins).
2. Select the plus button, then **Add custom MCP server**.
3. Enter **Unitlab** as the name and add a short description.
4. Under **Connection**, enter `https://api.unitlab.ai/mcp`.
5. Configure OAuth authentication and review the connection information.
6. Create and install the plugin, completing Unitlab sign-in and authorization when prompted.
7. Start a new chat and use **@** to select the Unitlab plugin.

Availability of custom MCP servers depends on your account and workspace policies.

[Official ChatGPT connection guide](https://developers.openai.com/plugins/deploy/connect-chatgpt).

## Cursor

Add the following server entry to `~/.cursor/mcp.json` for a user-wide configuration:

```json
{
  "mcpServers": {
    "unitlab": {
      "url": "https://api.unitlab.ai/mcp"
    }
  }
}
```

Preserve existing server entries when editing this file. For a project-specific configuration, use `.cursor/mcp.json` in that project.

Connect Unitlab in Cursor and complete OAuth sign-in when prompted.

[Official Cursor MCP guide](https://cursor.com/docs/mcp).

## Gemini CLI

Run:

```bash
gemini mcp add --transport http unitlab https://api.unitlab.ai/mcp
```

Start Gemini CLI and run:

```
/mcp auth unitlab
```

Complete Unitlab sign-in and consent. Add `--scope user` to the `gemini mcp add` command if you want the configuration available across projects.

[Official Gemini CLI MCP guide](https://geminicli.com/docs/tools/mcp-server/).

## VS Code

Use the Command Palette command **MCP: Add Server**, choose an HTTP server, and enter:

```
https://api.unitlab.ai/mcp
```

Follow the configuration, trust, and OAuth prompts shown by VS Code. Use an MCP-enabled chat mode to call the server.

If the `code` command-line launcher is installed, you can also add the server with:

```bash
code --add-mcp "{\"name\":\"unitlab\",\"type\":\"http\",\"url\":\"https://api.unitlab.ai/mcp\"}"
```

[Official VS Code MCP setup guide](https://code.visualstudio.com/docs/agent-customization/mcp-servers).

## Other MCP clients

Add a remote MCP server with the Unitlab address. The client must support **Streamable HTTP** and **OAuth authorization**. Sign in, select a workspace, and approve access when prompted.

Unitlab exposes standard discovery endpoints for clients implementing the connection:

```
https://api.unitlab.ai/.well-known/oauth-protected-resource/mcp
https://api.unitlab.ai/.well-known/oauth-authorization-server
```

The authorization server supports authorization-code and refresh-token grants, PKCE with `S256`, and the `unitlab:read` and `unitlab:write` scopes. The protected resource advertises the required read scope; write permission is enforced on individual operations.

## Verify the connection

Send this prompt in the assistant:

> Check my Unitlab connection. Show the workspace name, whether this connection can write, and the projects I can access.

The assistant should call `get_context` followed by `list_projects`. An empty project list can mean the workspace has no projects or your role is restricted to its eligible workflow stages.

Next, try the [image-folder quickstart](https://docs.unitlab.ai/api-sdk-cli/mcp/quickstart).

## Manage or remove a connection

Open **Settings → Connected assistants** in Unitlab. The table shows the assistant, access level, member, connection date, and last-use time.

* **Edit permissions** changes the permission list on your own connection. The changes apply on the next call.
* **Disconnect** revokes the connection's access. Saved projects and annotations remain.
* To change the workspace or move from Read only to Read and write, reconnect and approve the new selection.

See [Authentication and permissions](https://docs.unitlab.ai/api-sdk-cli/mcp/authentication-and-permissions) for the complete access model and [Troubleshooting](https://docs.unitlab.ai/api-sdk-cli/mcp/troubleshooting) if connection or sign-in fails.