# Tools

> Learn about the tools available in the Directus remote MCP server and how they enable AI-powered content management.

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.

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

**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.

</callout>

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

<table>
<thead>
  <tr>
    <th>
      Tool
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <strong>
        search
      </strong>
    </td>
    
    <td>
      Searches the available Directus tools or loads full details for selected tool names
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        execute
      </strong>
    </td>
    
    <td>
      Runs a tool selected through <code>
        search
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        schema
      </strong>
    </td>
    
    <td>
      Reads collection and field schema information directly
    </td>
  </tr>
</tbody>
</table>

Registry mode moves discovery into Directus and follows this sequence:

1. Call `search` with a query to discover relevant tools.
2. Call `search` with the selected tool names to load their instructions and input types.
3. 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.

<table>
<thead>
  <tr>
    <th>
      Consideration
    </th>
    
    <th>
      Default mode
    </th>
    
    <th>
      Registry mode
    </th>
  </tr>
</thead>

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

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

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.

</callout>

## Default Mode Tools

The remote MCP server provides the following tools:

<table>
<thead>
  <tr>
    <th>
      Tool
    </th>
    
    <th>
      Description
    </th>
    
    <th>
      Use Cases
    </th>
  </tr>
</thead>

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

## 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.

<callout color="info" icon="i-lucide-code" to="https://github.com/directus/directus/blob/3f3772d8a0e8d28f61cfa3ea89a75fee9ef9e6a2/api/src/ai/tools/system/prompt.md">

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

</callout>

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:

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