> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encord.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Encord MCP / Merlin
> Control Encord directly from your AI assistant using Merlin, Encord's MCP server.
Merlin is Encord's Model Context Protocol (MCP) server. It exposes Encord's platform as a set of tools your AI assistant can call, so you can create projects, define ontologies, check analytics, and more, all through natural language, without leaving your AI tool.
## What Merlin can do
Once connected, your AI assistant can take actions on your behalf across the Encord platform:
| Category | What you can ask |
| ------------------ | ------------------------------------------------------------------------------------------------ |
| **Projects** | List your Projects, create new annotation Projects with a chosen Ontology, Dataset, and Workflow |
| **Ontologies** | List Ontologies, create a label taxonomy with objects, classifications, and nested attributes |
| **Datasets** | Browse and search your Datasets |
| **Workflows** | List available Workflow templates (annotate → review, consensus, double review, pre-labelling) |
| **Editor layouts** | Configure custom annotation editor layouts for evaluation, rating, and scoring tasks |
| **Analytics** | Query task throughput, time spent, and collaborator performance for any Project |
## Prerequisites
* An Encord account (cloud). Merlin uses OAuth via WorkOS and is not available on on-premises or air-gapped deployments.
* A supported MCP client (see [Connect your AI assistant](#connect-your-ai-assistant) below).
## Connect your AI assistant
Run the following command in your terminal:
```bash theme={"dark"}
claude mcp add --transport http encord-merlin https://mcp.encord.com
```
The first time you call a Merlin tool, Claude Code opens a browser to sign in with your Encord account.
**For Team/Enterprise plans:**
1. An organization admin must first add the connector in [**Admin settings** > **Connectors**](https://claude.ai/settings/connectors) with the URL `https://mcp.encord.com`.
2. Members then add the same connector under [**Settings** > **Connectors**](https://claude.ai/settings/connectors).
3. Restart Claude Desktop for the changes to take effect.
**For Free/Pro plans:** Add the server to your `claude_desktop_config.json`:
```json theme={"dark"}
{
"mcpServers": {
"encord-merlin": {
"type": "http",
"url": "https://mcp.encord.com"
}
}
}
```
Add the following to your Cursor MCP configuration:
```json theme={"dark"}
{
"mcpServers": {
"encord-merlin": {
"type": "http",
"url": "https://mcp.encord.com"
}
}
}
```
Merlin uses the standard MCP streamable-HTTP transport. Point any MCP-compatible client to:
```
https://mcp.encord.com
```
The client runs an OAuth authorization flow against WorkOS on first use. Every WorkOS-backed login method (SSO, email, etc.) is supported.
## Authentication
Merlin authenticates using **OAuth**. When your AI assistant first calls a Merlin tool it opens a browser window and prompt you to sign in with your Encord credentials. The session is managed by WorkOS. Merlin itself never stores your credentials.
You must sign in as an Encord user whose account was created (or backfilled) after Merlin launched. If your sign-in succeeds but tool calls are rejected, contact your workspace admin.
Org-level MFA enforcement is not yet supported for Merlin. Requests from organizations with mandatory MFA will be rejected.
## Merlin with Workspaces
If you belong to only one Encord Workspace, Merlin automatically uses that Workspace. No additional setup is required.
If you belong to multiple Workspaces, Merlin needs to know which Workspace you want to work in before it can perform actions for you.
The first time you use Merlin, your AI assistant may ask you to choose an active Workspace. Once selected, Merlin continues using that Workspace for future requests until you choose a different one.
To switch Workspaces later, simply tell your AI assistant which Workspace you would like to use. Merlin lists your available Workspaces, asks you to confirm your selection, and then sets that Workspace as your active Workspace.
Example:
"Show me my available Workspaces."
"Switch my active Workspace to Data Operations."
## Example prompts
Once connected, you can talk to your AI assistant naturally. A few examples:
**Setting up a new project end-to-end:**
> "Create an ontology for vehicle detection with bounding box classes for car, truck, and motorcycle. Then create a project called 'Vehicle QA' using that ontology and my existing dataset 'Street Footage'."
**Checking project health:**
> "How many tasks were completed in my 'Pedestrian Detection' project last month, and who were the top three annotators by output?"
**Exploring what's available:**
> "List all my projects that are currently active and show me which ones I'm an admin on."
**Configuring an evaluation workflow:**
> "Set up a custom editor layout on project 'RLHF Round 3' that shows the media and a preference rating question side by side."
## Available tools reference
| Tool | Description |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_project_tool` | Create an annotation project. Accepts a title, description, ontology, one or more datasets (or a storage folder), and an optional workflow template. Returns a direct link to the new project. |
| `list_projects_tool` | List your projects, most recently created first. Supports title search and pagination (50 per page). |
| Tool | Description |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_ontology_tool` | Create a label taxonomy. Define objects (things to localize, with a shape) and classifications (frame-level questions). Attributes support radio, checklist, text, and numeric types, with radio options supporting up to three levels of nesting. |
| `list_ontologies_tool` | List your ontologies, most recently created first, with cursor-based pagination. |
| Tool | Description |
| -------------------- | ------------------------------------------------------------------------- |
| `list_datasets_tool` | List your datasets with optional title/description search and pagination. |
| Tool | Description |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_workflow_templates_tool` | List all workflow templates, including Encord's built-in templates and your saved custom templates. Use this to find the right template UUID before creating a project that needs a non-default review process. |
| Tool | Description |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_project_layout_features_tool` | List the ontology classifications a custom editor layout can reference for a given project. Call this before `set_project_layout_tool` to get the valid `schema_feature_uuid` values. |
| `set_project_layout_tool` | Apply a custom annotation editor layout to a project. Useful for evaluation, preference rating, and rubric-scoring tasks where the editor functions as a structured form. |
Analytics tools are available to **project admins and team managers** only. Time windows default to the last 30 days and cannot exceed 90 days.
| Tool | Description |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `project_throughput_tool` | Count task actions (completions, approvals, rejections, skips) over a time window. Optional `group_by` splits results by user, day, or workflow stage. |
| `project_time_summary_tool` | Total time spent on a project, broken down by stage, user, or day. |
| `project_collaborator_performance_tool` | Rank collaborators by task counts, rejection rate, label activity, and time — for either the annotation or review stage. |
| Tool | Description |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `list_workspaces_tool` | List all Encord Workspaces you have access to. |
| `set_active_workspace_tool` | Set the Workspace Merlin should use for future requests. Required only for users who belong to multiple Workspaces. |