# Installation

> Set up the Directus MCP server and connect your AI tools in under 5 minutes.

Get AI assistants connected to your Directus instance in three simple steps. The MCP server is built into Directus with no additional setup required.

<callout color="info" icon="i-lucide-info">

**MCP requires Directus v11.12+**. For older versions, use the [Local MCP alternative](/guides/ai/mcp/local-mcp).

</callout>

## Quick Setup

The Directus MCP server is disabled by default and must be manually enabled. When enabled, it uses the same permissions as the user account you connect with. AI tools can only access what that user is allowed to see and do.

System administrators can completely disable MCP functionality through [configuration environment variables](/configuration/ai#model-context-protocol).

## Choose a Tool Mode

Tool definitions include names, descriptions, and input schemas. When an MCP client loads every definition into the model prompt, those definitions consume context before the model receives your conversation, data, or tool results. This cost grows as you connect more MCP servers.

Directus supports two tool modes so you can choose where tool discovery happens:

<table>
<thead>
  <tr>
    <th>
      Mode
    </th>
    
    <th>
      Tool discovery
    </th>
    
    <th>
      Use it when
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <strong>
        Default
      </strong>
    </td>
    
    <td>
      Your MCP client selects from the individual Directus tools
    </td>
    
    <td>
      Your client searches or loads tools on demand, or you want per-tool approval controls
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Registry
      </strong>
    </td>
    
    <td>
      Directus exposes a small registry that the model searches
    </td>
    
    <td>
      Your client loads every tool definition upfront, has a tool-count limit, or spends too much context on unused tools
    </td>
  </tr>
</tbody>
</table>

<callout color="primary" icon="i-lucide-lightbulb" title="Recommendation">

Use one discovery layer. Prefer the default mode when your client already provides tool search or deferred loading. Otherwise, use registry mode to protect the model's context window.

</callout>

### Default Mode

The default MCP URL exposes each Directus tool separately to the client:

```text
https://your-directus-url.com/mcp
```

Prefer this mode when your client provides its own tool search or deferred loading. The client can keep unused schemas out of the model context while preserving the names, descriptions, annotations, and approval settings of individual Directus tools.

For example, [Claude Code enables MCP Tool Search by default](https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search) on supported models, and current versions of [Cursor dynamically load the MCP tools they need](https://cursor.com/blog/dynamic-context-discovery). Custom clients using supported OpenAI models can also [opt into tool search](https://developers.openai.com/api/docs/guides/tools-tool-search). In these cases, registry mode usually duplicates work the client already performs.

Some clients use tool search only after reaching a threshold. For example, VS Code's experimental [virtual tools setting](https://code.visualstudio.com/docs/agents/reference/ai-settings) only activates above a default threshold of 128 tools. Registry mode can still reduce upfront context below that threshold.

Client-side search can also depend on the client version, selected model, model provider, proxy, or settings. Use registry mode if your client falls back to loading every tool upfront.

### Registry Mode

Registry mode exposes only `search`, `execute`, and `schema` to the client. The model searches for the right Directus tool, loads only its input details, then calls it through `execute`.

```text
https://your-directus-url.com/mcp?tool_mode=registry
```

Use registry mode when your client sends all available tool definitions to the model, does not support tool search, or fails because too many tools are enabled. It keeps the initial Directus tool surface fixed at three tools regardless of how many tools Directus provides.

This smaller initial surface leaves more of the context window for your instructions, conversation history, Directus schema, and results. It can also make tool selection easier by removing unrelated definitions from the model's immediate choices.

Registry mode has two trade-offs:

- The model normally makes extra `search` calls before `execute`, which can add latency and tool-call overhead.
- The MCP client shows most operations as `execute`, with the underlying Directus tool nested in its input. Tool pickers, call history, approval rules, and allow lists cannot treat `items`, `files`, `collections`, or other inner tools separately.

Authentication, Directus permissions, admin-only restrictions, and the **Allow Deletes** setting work the same in both modes. When using a static token in the URL, combine the parameters like this:

```text
https://your-directus-url.com/mcp?tool_mode=registry&access_token=your-generated-token
```

<callout color="warning" icon="i-lucide-triangle-alert">

Do not automatically approve `execute`. It can run both read and write operations, and the client cannot apply the underlying tool's individual approval policy. Use scoped Directus permissions and keep the **Allow Deletes** setting disabled unless you need it.

</callout>

## Choose an Authentication Method

Directus supports two ways to authenticate remote MCP clients. Use OAuth when your client supports remote server OAuth discovery and browser authorization. Use a static access token when your client requires a manually configured bearer token, header, or query parameter.

<steps level="3">

### Enable MCP in Directus

1. Log into your Directus admin as an administrator
2. Go to **Settings → AI → Model Context Protocol**
3. Click **Enabled** under **MCP Server** to activate the MCP server
![MCP Server Enabled](/img/mcp-settings-page-enable.png)
4. **Save the AI settings**

<callout color="primary">

Most users can keep the default settings. The MCP server is now ready at `https://your-directus-url.com/mcp`.

</callout>

### Configure Authentication

#### Recommended: OAuth

OAuth lets users sign in to Directus in the browser and approve MCP access from a consent page. The issued token is scoped to the MCP endpoint.

For self-hosted projects, enable the OAuth server and a client registration method. Prefer Client ID Metadata Document registration when your client supports it because it avoids unauthenticated local client creation:

```bash [.env]
MCP_OAUTH_ENABLED=true
MCP_OAUTH_CIMD_ENABLED=true
PUBLIC_URL=https://directus.example.com
```

Use `MCP_OAUTH_CIMD_ENABLED=true` for [Client ID Metadata Document registration](/guides/ai/mcp/oauth#client-id-metadata-document), `MCP_OAUTH_DCR_ENABLED=true` for [Dynamic Client Registration](/guides/ai/mcp/oauth#dynamic-client-registration), or both if you intentionally support both onboarding paths.

After restarting Directus, go to **Settings** > **AI** > **Model Context Protocol**, enable **OAuth Enabled**, and enable the matching client registration setting for the project.

![MCP OAuth settings with OAuth, Dynamic Client Registration, and Client ID Metadata Document enabled](/img/mcp-oauth-settings-toggles.png)

Read the [MCP OAuth guide](/guides/ai/mcp/oauth) for the full authorization flow, client registration behavior, and revocation steps.

#### Fallback: Static Access Token

Static access tokens work with clients that do not support MCP OAuth. Use a dedicated Directus user when possible.

<callout color="primary" icon="i-lucide-user-plus" title="Create a dedicated MCP user">

1. Navigate to **User Directory**.
2. Click **Create User**.
3. Configure the user:

  - **Name**: `Your Name - MCP User` or similar
  - **Email**: Email is not required for MCP operations.
  - **Role**: Create a new role or use an existing role with appropriate [permissions](/guides/auth/access-control).
4. Open the user profile.
5. Scroll to the **Token** field and generate a new token.
6. Copy the token, then save the user.

</callout>

<callout color="warning" icon="i-lucide-user" title="Use an existing user">

Avoid using your personal admin account for AI operations. If you must use an existing user, open that user profile, generate a token from the **Token** field, copy it, and save the user.

</callout>

### Connect Your AI Client

You control the LLM integration. This tool connects to your own language model - either self-hosted or via a public service like OpenAI, Anthropic, or others.

If your client supports MCP OAuth, connect to `https://your-directus-url.com/mcp` without adding an access token to the URL or headers. Use Client ID Metadata Document registration when your client supports it. Use Dynamic Client Registration when the client requires it.

<accordion type="single">
<accordion-item icon="i-simple-icons-openai" label="ChatGPT">

#### OAuth

ChatGPT currently uses Dynamic Client Registration.

1. Log into [ChatGPT](https://chat.openai.com/) with Pro/Teams account.
2. Go to **Settings** > **Apps & Connectors**.
3. Click **Create** in the top-right corner.
4. Configure:

  - **Name**: Directus MCP
  - **MCP Server URL**: `https://your-directus-url.com/mcp`
  - **Authentication**: OAuth
5. Open **Advanced OAuth settings** and use Dynamic Client Registration.

![ChatGPT Advanced OAuth settings showing the registration method selector](/img/mcp-oauth-chatgpt-advanced-settings.png)

1. Click **Create** to save the connector and complete the browser authorization flow.

#### Static Access Token

Use this fallback when OAuth is not available for your setup.

1. Click **Create** in **Settings** > **Apps & Connectors**.
2. Configure:

  - **Name**: Directus MCP
  - **MCP Server URL**: `https://your-directus-url.com/mcp?access_token=your-generated-token`
  - **Authentication**: No authentication
3. Click **Create** to save the connector.

</accordion-item>

<accordion-item icon="i-simple-icons-anthropic" label="Claude Desktop">

#### OAuth

Claude Desktop works with Client ID Metadata Document registration and Dynamic Client Registration. Prefer CIMD when available.

1. Open your connector settings.
2. Add a custom connector.
3. Configure:

  - **Name**: Directus MCP
  - **Server URL**: `https://your-directus-url.com/mcp`
4. Complete the browser authorization flow when prompted.

#### Static Access Token

1. Open **Settings** > **Connectors**.
2. Click **Add custom connector**.
3. Configure the connector:

  - **Name**: Directus MCP
  - **Server URL**: `https://your-directus-url.com/mcp?access_token=your-generated-token`
4. Click **Add** to save the connector.
5. Review and accept the permissions when prompted.

</accordion-item>

<accordion-item icon="i-simple-icons-anthropic" label="Claude.ai">

#### OAuth

Claude.ai works with Client ID Metadata Document registration and Dynamic Client Registration. Prefer CIMD when available.

1. Open your connector settings.
2. Add a custom connector.
3. Configure:

  - **Name**: Directus MCP
  - **Server URL**: `https://your-directus-url.com/mcp`
4. Complete the browser authorization flow when prompted.

</accordion-item>

<accordion-item icon="i-simple-icons-anthropic" label="Claude Code">

#### OAuth

Claude Code works with Client ID Metadata Document registration and Dynamic Client Registration. Prefer CIMD when available.

1. Install [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code/quickstart).
2. Add Directus MCP server using the command line:

```bash
claude mcp add --transport http directus https://your-directus-url.com/mcp
```

1. Start Claude Code and complete the browser authorization flow when prompted.

#### Static Access Token

Use a static token only when OAuth is not available for your setup.

```bash
claude mcp add --transport http directus https://your-directus-url.com/mcp \
  --header "Authorization: Bearer your-generated-token"
```

</accordion-item>

<accordion-item icon="i-simple-icons-raycast" label="Raycast">

#### OAuth

Raycast currently uses Dynamic Client Registration.

1. Download [Raycast](https://raycast.com/).
2. Open Raycast and search for "MCP Servers".
3. Configure Directus MCP server through the UI:

  - **Name**: Directus MCP
  - **URL**: `https://your-directus-url.com/mcp`
4. Save the configuration and complete the browser authorization flow.

#### Static Access Token

Use this fallback when OAuth is not available for your setup.

1. Open Raycast and search for "MCP Servers".
2. Configure Directus MCP server through the UI:

  - **Name**: Directus MCP
  - **URL**: `https://your-directus-url.com/mcp?access_token=your-generated-token`
3. Save the configuration.

</accordion-item>

<accordion-item icon="i-simple-icons-visualstudiocode" label="VS Code">

#### OAuth

VS Code uses Client ID Metadata Document registration and does not fall back to Dynamic Client Registration.

1. Install VS Code 1.102+ and the [GitHub Copilot extension](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot).
2. Create or edit `mcp.json` in your workspace `.vscode` folder or user settings.
3. Add this configuration:

```json
{
  "servers": {
    "directus": {
      "url": "https://your-directus-url.com/mcp",
      "type": "http"
    }
  }
}
```

1. Use MCP tools in Agent mode from the Chat view and complete the browser authorization flow when prompted.

#### Static Access Token

Use this fallback when OAuth is not available for your setup.

```json
{
  "servers": {
    "directus": {
      "type": "http",
      "url": "https://your-directus-url.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:directus-token}"
      }
    }
  },
  "inputs": [
    {
      "id": "directus-token",
      "type": "promptString",
      "description": "Directus Access Token",
      "password": true
    }
  ]
}
```

VS Code will prompt you for your Directus token when the server starts.

</accordion-item>

<accordion-item icon="vscode-icons:file-type-cursorrules" label="Cursor">

#### OAuth

Cursor currently uses Dynamic Client Registration.

[![Install MCP Server in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=directus&config=eyJ1cmwiOiJodHRwczovL3lvdXItZGlyZWN0dXMtdXJsLmNvbS9tY3AifQ%3D%3D)

1. **One-click install**: Click the button above to automatically configure Directus MCP in Cursor.
2. **Manual setup**: Alternatively, create `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "directus": {
      "url": "https://your-directus-url.com/mcp"
    }
  }
}
```

1. Replace `your-directus-url.com` with your Directus URL and complete the browser authorization flow when prompted.

#### Static Access Token

[![Install MCP Server in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=directus&config=eyJ1cmwiOiJodHRwczovL3lvdXItZGlyZWN0dXMtdXJsLmNvbS9tY3AiLCJoZWFkZXJzIjp7IkF1dGhvcml6YXRpb24iOiJCZWFyZXIgRElSRUNUVVNfVE9LRU4ifX0%3D)

1. **One-click install**: Click the button above to automatically configure Directus MCP in Cursor.
2. **Manual setup**: Alternatively, create `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "directus": {
      "url": "https://your-directus-url.com/mcp",
      "headers": {
        "Authorization": "Bearer your-generated-token"
      }
    }
  }
}
```

1. Replace `your-directus-url.com` and `your-generated-token` with your values.

</accordion-item>
</accordion>
</steps>

## Verify Connection

Once connected, test your setup with a simple question about your Directus instance:

<chat :messages="[{"role":"user","content":"Can you tell me about my Directus schema?"},{"role":"assistant","content":"I'll help you explore your Directus schema. Let me start by getting my role information and then examine your database structure.","toolInvocations":[{"toolCallId":"system-prompt","toolName":"system-prompt","state":"result"},{"toolCallId":"schema","toolName":"schema","state":"result"}]}]" chatId="verify-connection">



</chat>

## User Permissions

Configure your AI user's role based on what you want them to do:

**Content Editor Role** (recommended for most users):

- **Collections**: Read/Create/Update on your content collections
- **Files**: Read/Create/Update/Delete
- **Folders**: Read/Create/Update/Delete
- **System Collections**: Read only

**Developer Role** (required for schema management):

- All content permissions above, plus:
- **Collections**: Full CRUD access
- **Fields**: Full CRUD access
- **Relations**: Full CRUD access
- **Flows**: Full CRUD access

or add the administrator role to your MCP user.

<callout color="info" icon="i-lucide-info">

**Note**: The MCP server uses your existing permissions and access policy settings. AI tools can only access what you explicitly allow - just like any other Directus user. See [Access Control](/guides/auth/access-control) for more information.

</callout>

---

## MCP Server Settings

![MCP Server Settings](/img/mcp-settings-page.png)

Access advanced options in **Settings → AI → Model Context Protocol**:

<table>
<thead>
  <tr>
    <th>
      Setting
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <strong>
        MCP Server
      </strong>
    </td>
    
    <td>
      Toggle
    </td>
    
    <td>
      Disabled
    </td>
    
    <td>
      Connect AI/LLM tools to your Directus project via Model Context Protocol (MCP). This enables AI assistants to read and interact with your Directus data securely.
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Allow Deletes
      </strong>
    </td>
    
    <td>
      Toggle
    </td>
    
    <td>
      Disabled
    </td>
    
    <td>
      Enable deletion of items, files, flows, fields, relations, and collections through MCP tools. <strong>
        WARNING: May cause data loss.
      </strong>
      
       Disabled by default for safety.
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        AI Prompts Collection
      </strong>
    </td>
    
    <td>
      Select
    </td>
    
    <td>
      No collection selected
    </td>
    
    <td>
      Select a collection to enable reusable prompt templates. Select existing collection or click "Generate AI Prompts collection..." to create one automatically.
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Use System Prompt
      </strong>
    </td>
    
    <td>
      Toggle
    </td>
    
    <td>
      Enabled
    </td>
    
    <td>
      Use the default system prompt to guide LLM behavior. Disable to remove or override with your own prompt below.
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Custom System Prompt
      </strong>
    </td>
    
    <td>
      Rich Text
    </td>
    
    <td>
      Empty
    </td>
    
    <td>
      Custom system prompt to replace the default. Leave empty to use default (if enabled above).
    </td>
  </tr>
</tbody>
</table>

---

## Next Steps

Your MCP server is ready! Here's what to explore:

<card-group>
<card icon="i-lucide-zap" title="See What's Possible" to="/guides/ai/mcp/use-cases">

Real examples of AI-powered content workflows that save hours of manual work.

</card>

<card icon="i-lucide-wrench" title="Available Tools" to="/guides/ai/mcp/tools">

Complete reference of MCP tools and their capabilities.

</card>

<card icon="i-lucide-message-circle" title="Custom Prompts" to="/guides/ai/mcp/prompts">

Create reusable prompt templates for consistent AI interactions.

</card>

<card icon="i-lucide-shield" title="Security Guide" to="/guides/ai/mcp/security">

Essential security practices for using MCP safely with your Directus data.

</card>

<card icon="i-lucide-circle-question-mark" title="Troubleshooting" to="/guides/ai/mcp/troubleshooting">

Common issues and solutions when setting up and using the Directus MCP server.

</card>
</card-group>