Tools

The Directus remote MCP server provides a set of tools that allow AI assistants to interact with your Directus instance. These tools enable various operations while respecting your existing permissions and security settings.

Note: The remote MCP server uses unified tools compared to the local MCP server. For example, it has a single items tool that handles all CRUD operations, while the local MCP has separate read-items, create-item, update-item, and delete-item tools.

Tool Modes

MCP clients receive tool names, descriptions, and input schemas from the server. Clients that put every definition into the model prompt spend part of the context window on tools the model may never use. Directus offers two modes to control that cost.

Default Mode

Connect to /mcp to expose each Directus tool separately. This mode preserves the complete MCP interface, including individual tool names, descriptions, annotations, and client approval settings.

Use default mode when your client searches or loads MCP tools on demand. Client-side discovery solves the context-window problem while keeping direct calls to tools such as items, files, and collections.

Registry Mode

Connect to /mcp?tool_mode=registry to expose three root tools:

Tool	Description
search	Searches the available Directus tools or loads full details for selected tool names
execute	Runs a tool selected through `search`
schema	Reads collection and field schema information directly

Registry mode moves discovery into Directus and follows this sequence:

Call search with a query to discover relevant tools.
Call search with the selected tool names to load their instructions and input types.
Call execute with the tool name and input.

The schema tool stays available directly because models commonly need the data model before working with content. Only the selected inner tool details enter the conversation through search, while the underlying operation still uses the connected user's Directus permissions and the project's MCP settings.

Use registry mode when the client loads all MCP tool definitions upfront, lacks tool search, or reaches a tool-count limit. The smaller initial tool surface leaves more context for your prompt, conversation history, schema, and results.

Consideration	Default mode	Registry mode
Initial Directus tool surface	All individual tools	`search`, `execute`, and `schema`
Context usage	Depends on the client's loading behavior	Bounded initial tool definitions
Tool calls	Calls the selected tool directly	Usually searches, loads details, then calls `execute`
Client approvals and allow lists	Can target individual tools	Can target only the root tools
Client tool UI and call history	Shows individual Directus tools	Shows `execute` with the inner tool in its input
Compatibility	Works with existing MCP configurations	Requires adding `tool_mode=registry` to the URL

Use the default mode when your client already provides tool search. Registry mode duplicates that discovery step and replaces individual client approval rules with a single execute policy.

Default Mode Tools

The remote MCP server provides the following tools:

Tool	Description	Use Cases
system-prompt	Provides context about Directus and your instance	Start of session, understanding capabilities
items	Complete CRUD operations on collection items	Content management, data operations
schema	Read collection and field schema information	Understanding data structure, exploring collections
collections	Manage Directus collections (database tables)	Creating/modifying collections, database structure
fields	Manage collection fields and their configuration	Adding/modifying fields, changing data types
relations	Create and manage relationships between collections	Setting up relationships, data modeling
files	File management and metadata operations	Managing uploads, organizing media
assets	Retrieve file content as base64 for AI processing	Image analysis, content processing
flows	Automation workflow management	Creating automations, workflow design
operations	Manage individual operations within flows	Building automation logic, flow operations
trigger-flow	Execute manual flows programmatically	Running automations, bulk operations
folders	Manage file organization structure	Organizing files, creating folder structures

System Prompt Tool

The system-prompt tool provides the AI assistant with specialized knowledge about Directus and your instance configuration. It should typically be called at the beginning of each session.

This tool works like a system prompt for LLMs, but it's delivered as a tool call instead of being built into the conversation. The AI is instructed to call this tool first to load Directus-specific knowledge into the conversation context. It won't override any system prompts or instructions from your MCP client.

View the current system prompt on GitHub to see exactly what instructions the AI receives about working with Directus.

You can customize the system prompt or disable it entirely in Settings → AI → Model Context Protocol.

Best Practices

When working with the Directus MCP server tools:

Reference your Directus instance: Mention my Directus instance or my Directus project to help the AI understand it should use tools.
AI handles context automatically: The AI should call system prompt and schema tools as needed based on your requests.
Use scoped permissions: Create dedicated MCP users with minimal required permissions.
Test in development: Try operations in a development environment first.
Review AI actions: Always check what the AI is doing before approving tool calls.

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

Use Cases

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

Prompts

Learn how to configure and use stored prompts with the Directus MCP Server.