Installation | Directus Docs

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

MCP requires Directus v11.12+. For older versions, use the Local MCP alternative.

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.

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.

Enable MCP in Directus

Log into your Directus admin as an administrator
Go to Settings → AI → Model Context Protocol
Click Enabled under MCP Server to activate the MCP server
Save the AI settings

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

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:

.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, MCP_OAUTH_DCR_ENABLED=true for 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

Read the MCP OAuth guide 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.

Navigate to User Directory.
Click Create User.
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.
Open the user profile.
Scroll to the Token field and generate a new token.
Copy the token, then save the 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.

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.

OAuth

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

Install Claude Code CLI.
Add Directus MCP server using the command line:

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

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.

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

OAuth

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

Install VS Code 1.102+ and the GitHub Copilot extension.
Create or edit mcp.json in your workspace .vscode folder or user settings.
Add this configuration:

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

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.

{
  "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.

OAuth

Cursor currently uses Dynamic Client Registration.

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

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

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

Static Access Token

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

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

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

Verify Connection

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

Can you tell me about my Directus schema?

I'll help you explore your Directus schema. Let me start by getting my role information and then examine your database structure.

Called system-prompt

Called schema

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.

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 for more information.

MCP Server Settings

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

Setting	Type	Default	Description
MCP Server	Toggle	Disabled	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.
Allow Deletes	Toggle	Disabled	Enable deletion of items, files, flows, fields, relations, and collections through MCP tools. WARNING: May cause data loss. Disabled by default for safety.
AI Prompts Collection	Select	No collection selected	Select a collection to enable reusable prompt templates. Select existing collection or click "Generate AI Prompts collection..." to create one automatically.
Use System Prompt	Toggle	Enabled	Use the default system prompt to guide LLM behavior. Disable to remove or override with your own prompt below.
Custom System Prompt	Rich Text	Empty	Custom system prompt to replace the default. Leave empty to use default (if enabled above).

Next Steps

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

See What's Possible

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

Available Tools

Complete reference of MCP tools and their capabilities.

Custom Prompts

Create reusable prompt templates for consistent AI interactions.

Security Guide

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

Troubleshooting

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

Get once-a-month release notes & real‑world code tips...no fluff. 🐰

Overview

Connect AI assistants directly to your Directus instance. Let Claude, ChatGPT, and other AI tools manage your content without manual copy-pasting.

Use Cases

Real examples of how to use AI with your Directus content to save time and reduce repetitive work.