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.

Method	Use When
OAuth	Your MCP client supports remote server OAuth discovery and browser authorization. Users sign in to Directus and approve access from a consent page.
Static Access Token	Your MCP client requires a manually configured bearer token, header, or query parameter.

Use OAuth when the client supports it. Static access tokens remain useful for clients that do not support the MCP OAuth flow.

Read the MCP OAuth guide for browser-based authorization, client registration, and revocation.

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.

Generate Access Token

Navigate to User Directory
Click Create User with these settings:
- Name: Your Name - MCP User or similar
- Email: Email is not required for MCP operations
- Role: Create a new role or use existing role with appropriate permissions.
Generate an access token:
- Open the user profile
- Scroll to Token field → Generate new token
- Copy the token (you'll need it next)
- 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.

The examples below use static access tokens. If your client supports MCP OAuth, connect to https://your-directus-url.com/mcp without adding an access token to the URL or headers.

Choose your AI tool and follow the setup:

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

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

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

Start Claude Code and verify the connection:

# Start Claude Code
claude

# Ask Claude to test the connection
> "Can you tell me about my Directus schema?"

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": {
      "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
Use MCP tools in Agent mode from the Chat view

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.