MCP Tools

Directus MCP Tool Patterns

Reference for all 12 available MCP tools, their parameters, and usage patterns.

Critical: The Action Pattern

Every Directus MCP tool uses a unified action-based CRUD pattern. Instead of separate tools per operation, each tool accepts an action parameter:

action: "create" | "read" | "update" | "delete"

Always include the action parameter. This is different from platforms with separate list_*, create_*, get_* tools.

Getting Started

Always begin a session with these two calls:

1. Call system-prompt (no parameters) — loads Directus-specific context
2. Call schema (no parameters) — discovers all collections (discovery mode)

Tool Reference

Schema Discovery

Discovery Mode (list all collections)

Tool: schema
Input: {}

Returns: collections (names), collection_folders (UI grouping), notes (descriptions).

Detailed Mode (specific collections)

Tool: schema
Input: { "keys": ["posts", "categories"] }

Returns: field definitions (type, validation, defaults) and relationship mappings.

Items Tool — The Workhorse

Read with Query

Tool: items
Input: {
  "action": "read",
  "collection": "posts",
  "query": {
    "fields": ["id", "title", "status", "author.name"],
    "filter": { "status": { "_eq": "published" } },
    "sort": ["-date_created"],
    "limit": 25
  }
}

Create Items

Critical: data is ALWAYS an array, even for a single item.

Tool: items
Input: {
  "action": "create",
  "collection": "posts",
  "data": [{
    "title": "New Post",
    "status": "draft",
    "content": "Post content here"
  }]
}

Update Items

Tool: items
Input: {
  "action": "update",
  "collection": "posts",
  "keys": ["uuid-1"],
  "data": { "status": "published" }
}

Delete Items

Tool: items
Input: {
  "action": "delete",
  "collection": "posts",
  "keys": ["uuid-1", "uuid-2"]
}

Collections Tool

Create Collection

Tool: collections
Input: {
  "action": "create",
  "data": [{
    "collection": "articles",
    "schema": {},
    "meta": {
      "icon": "article",
      "note": "Blog articles",
      "color": "#2196F3"
    }
  }]
}

Use "schema": {} for real tables, "schema": null for folder-only collections.

Fields Tool

Create Fields

Critical: data is ALWAYS an array of field objects.

Tool: fields
Input: {
  "action": "create",
  "collection": "articles",
  "data": [{
    "field": "title",
    "type": "string",
    "meta": { "interface": "input", "note": "Article title" },
    "schema": { "is_nullable": false }
  }]
}

Field Types

string (max 255), text (unlimited), uuid, hash, integer, bigInteger, float, decimal, timestamp, datetime, date, time, boolean, json, csv, alias (virtual/relational).

Relations Tool

Create M2O Relation

Tool: relations
Input: {
  "action": "create",
  "collection": "posts",
  "field": "author",
  "data": {
    "collection": "posts",
    "field": "author",
    "related_collection": "authors",
    "schema": { "on_delete": "SET NULL" },
    "meta": {}
  }
}

Query System

Shared across items, files, folders, flows, operations:

Filter Operators

Logical Operators

{
  "_and": [
    { "status": { "_eq": "published" } },
    { "date": { "_gte": "2024-01-01" } }
  ]
}

{
  "_or": [
    { "role": { "_eq": "admin" } },
    { "role": { "_eq": "editor" } }
  ]
}

Deep Queries

Filter/sort/limit nested relations:

{
  "fields": ["title", "comments.text", "comments.author.name"],
  "deep": {
    "comments": {
      "_filter": { "status": { "_eq": "approved" } },
      "_sort": ["-date_created"],
      "_limit": 5
    }
  }
}

Best Practices

• Always call schema before write operations to understand field requirements
• Use fields parameter to reduce response size — avoid fetching ["*"] on large collections
• Filter server-side rather than fetching everything
• Paginate large datasets with limit and offset
• Process batch creates in groups of 10-25 items
• Check results after write operations
• Use search for full-text queries, filter for precise matching

Error Reference