Installation

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

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 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:

Default Mode

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

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 on supported models, and current versions of Cursor dynamically load the MCP tools they need. Custom clients using supported OpenAI models can also opt into 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 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.

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:

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

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.

MCP_OAUTH_ENABLED=true
MCP_OAUTH_CIMD_ENABLED=true
PUBLIC_URL=https://directus.example.com

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.

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

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

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

{
  "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
    }
  ]
}

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

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

::

Verify Connection

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

:::chat

chatId: "verify-connection" 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"

:::

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.

MCP Server Settings

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

Next Steps

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