Connect with MCP

Annota AI runs a remote server for the Model Context Protocol (MCP). Connect your AI assistant to it once, then ask the assistant to work with your datasets, annotations, documents, models, and knowledge bases from the same conversation. One connection covers Annota Studio and Annota Brain.

Before you start

You need:

• An Annota AI account. See Create your account.
• An AI client that supports remote MCP servers with Streamable HTTP and OAuth, such as Codex, Claude, or OpenCode.

The MCP integration is included in every plan.

Find the server URL

1. Sign in to Annota AI and select your organization.
2. In the Annota Studio sidebar, select Integrations.
3. Under MCP server, copy the Server URL with Copy URL.

The server URL is:

https://api.annota.ai/mcp

The Integrations page also has a setup prompt for each client. Select Copy prompt, paste it into your assistant, and it guides you through the setup and sign-in.

Set up your client

Choose your client and follow the steps. They match the Manual setup instructions on the Integrations page.

Codex

1. In Codex, open Settings > MCP servers > Add server. Name it annota-ai, choose Streamable HTTP, and paste the server URL.
2. Save the server and restart Codex when prompted. Select Authenticate next to annota-ai, then sign in with your Annota AI account in the browser.
3. Open a new conversation and use /mcp to check that annota-ai is connected.

If you have the Codex CLI installed, you can add the server and sign in from a terminal instead:

codex mcp add annota-ai --url 'https://api.annota.ai/mcp'
codex mcp login annota-ai

See the Codex MCP documentation for more options.

Claude

For Claude on the web or the desktop app:

1. In Claude, open Customize > Connectors. Select +, then Add custom connector. Name it Annota AI, paste the server URL, and select Add.
2. Find Annota AI in the connectors list and select Connect. Complete the sign-in with your Annota AI account in the browser.
3. Start a new conversation. Open + > Connectors and enable Annota AI to make its tools available to Claude.

On Claude Team and Enterprise, an owner must first add the connector in Organization settings > Connectors.

For Claude Code, copy the setup prompt from the Claude tab of the Integrations page and paste it into Claude Code. It adds the annota-ai server and guides you through the browser sign-in with /mcp.

See the Claude documentation on custom connectors for more details.

OpenCode

1. With OpenCode installed, add this entry to opencode.json in your project root, or to ~/.config/opencode/opencode.json for all projects. If the file already exists, merge the annota-ai entry into its mcp section.

   {
     "$schema": "https://opencode.ai/config.json",
     "mcp": {
       "annota-ai": {
         "type": "remote",
         "url": "https://api.annota.ai/mcp",
         "enabled": true
       }
     }
   }

2. From your project directory, run this command, then sign in with your Annota AI account in the browser that opens:

   opencode mcp auth annota-ai

3. Run opencode mcp list to check the server status, then open OpenCode in your project and ask it to use annota-ai.

See the OpenCode MCP documentation for more options.

Other clients work too if they support remote MCP servers with Streamable HTTP and OAuth. Add the server URL as a remote server and follow the client’s sign-in flow.

Sign in and authorize

The first time your client connects, it opens your browser. Sign in with your Annota AI account. The Authorize access screen then shows the name of the client and what it is asking for:

Permission	What it means
View, create, edit, and delete data you can access, and run processing that may consume credits.	The client can use every MCP tool on the data your account can reach.
Identify your account.	The client learns which Annota AI account signed in.
Read your profile information.	The client can read your name and profile details.
Read your email address.	The client can read the email address of your account.
Keep access even when you are not using the app.	The client stays connected without asking you to sign in every time.

The list shows only what your client requests. Select Authorize to connect or Deny to cancel.

Caution

The client can create, change, and delete data, and start work that uses credits. Only authorize clients you trust, and review what your assistant plans to do before it edits or deletes anything.

Check the connection

Start with a read-only request. Ask your assistant:

Show me the datasets available in my Annota AI organizations.

If it lists your datasets, the connection works.

What your assistant can do

Your assistant works on the same data you see in the app. For example, it can:

• List your organizations, datasets, assets, and labels.
• Upload images and documents, and create, edit, or delete annotations.
• Read and correct the OCR text of document pages, and set review statuses.
• Preview and start automatic annotation.
• Capture dataset versions and create exports.
• Manage models and training runs Private beta, in organizations where training is enabled.
• Create knowledge bases, search them, and read the pages it finds, so it can answer with sources using its own model.

The MCP server has no Brain chat tools: answers come from your assistant, not from Annota Brain. For the full list, see the MCP tools reference.

Permissions

The connection can access the organizations you belong to, with your existing permissions. Your assistant can only see and change what you can see and change in the app.

What your assistant creates belongs to you and stays private until you share it in the app. See Sharing and access.

Credits

Billable operations use the same credits as in the app, from your organization’s shared balance. For example:

• Uploading documents runs OCR.
• Automatic annotation is charged per image after inference, and runs only while the credit balance is positive. Your assistant can preview an estimate first.
• Knowledge bases use credits to index new or changed pages.
• Searching a knowledge base uses a few credits. Reading its documents is free.

See Credit usage for how each operation is counted, and pricing for your plan’s allowances.

Revoke access

You can disconnect a client at any time.

1. Open the user menu and, under Account, select Settings.
2. Select Security.
3. Under Authorized applications, find the client and select Revoke access.

The client loses its access, including tokens it already has. To connect again, it must ask for your authorization.

Next steps

• MCP tools reference
• Sharing and access
• Credit usage
• Account security