From 1883bfd480c7d9c44ae8dc465e7378c1edf9919d Mon Sep 17 00:00:00 2001 From: bryantgillespie Date: Thu, 6 Aug 2026 18:24:25 -0400 Subject: [PATCH 1/2] Document MCP tool modes and on-demand tool discovery --- content/guides/11.ai/1.assistant/1.setup.md | 20 +++- content/guides/11.ai/1.assistant/3.tools.md | 44 ++++---- content/guides/11.ai/1.assistant/4.tips.md | 15 ++- content/guides/11.ai/2.mcp/1.installation.md | 106 ++++++++++++++---- content/guides/11.ai/2.mcp/3.tools.md | 45 +++++++- .../guides/11.ai/2.mcp/5.troubleshooting.md | 6 + content/guides/11.ai/2.mcp/7.security.md | 1 + 7 files changed, 185 insertions(+), 52 deletions(-) diff --git a/content/guides/11.ai/1.assistant/1.setup.md b/content/guides/11.ai/1.assistant/1.setup.md index 01fd1fae8..6ccca1b3b 100644 --- a/content/guides/11.ai/1.assistant/1.setup.md +++ b/content/guides/11.ai/1.assistant/1.setup.md @@ -255,7 +255,15 @@ You are **Directus Assistant**, a Directus CMS expert with access to a Directus 1. Understand the user's task and what they need to achieve. 2. Discover schema if needed for task - **schema()** with no params → lightweight collection list or **schema({ keys: ["products", "categories"] })** → full field/relation details -3. Use other tools as needed to achieve the user's task. +3. Discover task-specific tools with **search({ query })** before saying a tool is unavailable. For example, use search + for "create collections", "add fields", or "create relationships" before claiming schema mutation tools are missing. +4. Load selected tool details with one batched **search({ names: ["collections", "fields", "relations"] })** call before + executing. Omit `query` in detail calls. Query results only identify candidate tools; detail results explain the + required inputs. +5. Execute detailed tools with **execute({ name, input })**, where **name** is the discovered Directus tool name like + "collections", "fields", or "relations". Never pass root tool names like "search" or "execute" as + the execute name. +6. Use other tools as needed to achieve the user's task. ### Content Items @@ -265,7 +273,8 @@ You are **Directus Assistant**, a Directus CMS expert with access to a Directus ### Schema & Data Changes -- **Confirm before modifying any schema**: Collections, fields, relations always need approval from the user. +- **Confirm before modifying any schema**: Collections, fields, relations need user approval. If the user already + explicitly asked you to create/update them, proceed without asking again. - **Check namespace conflicts**: Collection folders and regular collections share namespace. Collection folders are distinct from file folders. ### Safety Rules @@ -280,14 +289,15 @@ You are **Directus Assistant**, a Directus CMS expert with access to a Directus - Call tools immediately without explanatory text - Use parallel tool calls when possible -- If you don't have access to a certain tool, ask the user to grant you access to the tool from the chat settings. +- If you don't have access to a certain tool after searching for it, ask the user to grant access from chat settings. - If there are unused tools in context but task is simple, suggest disabling unused tools (once per conversation) ## Error Handling - Auto-retry once for clear errors ("field X required") +- If a tool result includes `next`, call that tool with that input before retrying. - Stop after 2 failures, consult user -- If tool unavailable, suggest enabling in chat settings +- If tool unavailable, search once for the matching capability, then suggest enabling it in chat settings ``` @@ -320,7 +330,7 @@ For details on creating prompts with variables, see [MCP Prompts](/guides/ai/mcp **Tips for controlling costs:** - Use faster, cheaper models (GPT-5 Nano, Claude Haiku 4.5, Gemini 2.5 Flash) for simple tasks - Use [Allowed Models](#configure-allowed-models) to restrict access to expensive models -- Disable unused tools - disabled tools are not loaded into context, reducing token usage +- Start a new conversation when switching tasks to avoid sending unrelated conversation history - Set spending limits in your provider dashboard: - [OpenAI](https://platform.openai.com/settings/organization/limits) - [Anthropic](https://console.anthropic.com/) diff --git a/content/guides/11.ai/1.assistant/3.tools.md b/content/guides/11.ai/1.assistant/3.tools.md index 771426e8b..1909327eb 100644 --- a/content/guides/11.ai/1.assistant/3.tools.md +++ b/content/guides/11.ai/1.assistant/3.tools.md @@ -7,6 +7,8 @@ headline: AI Assistant AI Assistant uses tools to perform actions on your behalf. Each tool handles a specific type of operation within Directus. +AI Assistant discovers system tools on demand: it searches the available tools and loads only the details it needs for the current task. This keeps tool definitions out of the context window until they are needed, leaving more room for your conversation, schema, and results with any model provider. You still configure approvals and availability for each underlying tool individually. + ::callout{icon="i-lucide-shield" color="info"} **Tools use your existing user permissions.** Users without admin access won't see Admin Only tools. If you can't access a collection or perform an action in Directus, the AI can't either. :: @@ -15,13 +17,13 @@ AI Assistant uses tools to perform actions on your behalf. Each tool handles a s These tools interact with your Directus instance via API to manage content, files, and schema. -| Tool | Description | -|------|-------------| -| :icon{name="material-symbols:database-search-outline" class="text-muted"} **Schema** | Explore collections, fields, and relationships (read-only) | -| :icon{name="material-symbols:box-outline" class="text-muted"} **Items** | Create, read, update, and delete items in your collections | -| :icon{name="material-symbols:folder-outline" class="text-muted"} **Files** | Manage file metadata, import from URLs, organize uploads | -| :icon{name="material-symbols:folder-open-outline" class="text-muted"} **Folders** | Create and organize folder structures for files | -| :icon{name="material-symbols:play-arrow-outline" class="text-muted"} **Trigger Flow** | Execute manual flows on demand | +| Tool | Description | +| ------------------------------------------------------------------------------------- | ---------------------------------------------------------- | +| :icon{name="material-symbols:database-search-outline" class="text-muted"} **Schema** | Explore collections, fields, and relationships (read-only) | +| :icon{name="material-symbols:box-outline" class="text-muted"} **Items** | Create, read, update, and delete items in your collections | +| :icon{name="material-symbols:folder-outline" class="text-muted"} **Files** | Manage file metadata, import from URLs, organize uploads | +| :icon{name="material-symbols:folder-open-outline" class="text-muted"} **Folders** | Create and organize folder structures for files | +| :icon{name="material-symbols:play-arrow-outline" class="text-muted"} **Trigger Flow** | Execute manual flows on demand | ### Admin Only @@ -29,13 +31,13 @@ These tools interact with your Directus instance via API to manage content, file Be careful when using these tools as deleting or modifying schema can result in data loss. :: -| Tool | Description | -|------|-------------| -| :icon{name="material-symbols:database-outline" class="text-muted"} **Collections** | Create, modify, and delete collections (database tables) | -| :icon{name="material-symbols:variable-add-outline" class="text-muted"} **Fields** | Add, configure, and remove fields within collections | -| :icon{name="material-symbols:hub-outline" class="text-muted"} **Relations** | Set up relationships between collections | -| :icon{name="material-symbols:bolt-outline" class="text-muted"} **Flows** | Create and manage automation workflows | -| :icon{name="material-symbols:offline-bolt-outline" class="text-muted"} **Operations** | Configure individual steps within flows | +| Tool | Description | +| ------------------------------------------------------------------------------------- | -------------------------------------------------------- | +| :icon{name="material-symbols:database-outline" class="text-muted"} **Collections** | Create, modify, and delete collections (database tables) | +| :icon{name="material-symbols:variable-add-outline" class="text-muted"} **Fields** | Add, configure, and remove fields within collections | +| :icon{name="material-symbols:hub-outline" class="text-muted"} **Relations** | Set up relationships between collections | +| :icon{name="material-symbols:bolt-outline" class="text-muted"} **Flows** | Create and manage automation workflows | +| :icon{name="material-symbols:offline-bolt-outline" class="text-muted"} **Operations** | Configure individual steps within flows | --- @@ -49,8 +51,6 @@ Page Context tools let the AI work directly with what's on your screen. They are | **Read Form Values** | Read current field values from the form on screen | | **Set Form Values** | Update field values on the current form | - - --- ## Tool Behavior @@ -59,16 +59,16 @@ Page Context tools let the AI work directly with what's on your screen. They are Each tool can be configured with one of three approval modes: -| Mode | Behavior | -|------|----------| -| :icon{name="material-symbols:check" class="text-success"} **Always Allowed** | Execute immediately without asking | -| :icon{name="material-symbols:approval-delegation-outline" class="text-warning"} **Needs Approval** | Show approval dialog before executing (default) | -| :icon{name="material-symbols:block-outline" class="text-error"} **Disabled** | Tool is hidden from AI and not loaded into context | +| Mode | Behavior | +| -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | +| :icon{name="material-symbols:check" class="text-success"} **Always Allowed** | Execute immediately without asking | +| :icon{name="material-symbols:approval-delegation-outline" class="text-warning"} **Needs Approval** | Show approval dialog before executing (default) | +| :icon{name="material-symbols:block-outline" class="text-error"} **Disabled** | Tool is unavailable to AI and excluded from tool discovery | Tool approval settings are stored locally in your browser and are unique to you. They won't sync to your Directus instance or affect other users. ::callout{icon="i-lucide-lightbulb" color="primary"} -**Disable unused tools to reduce costs.** Disabled tools are not sent to the AI provider, reducing token usage. If you only manage content, disable schema and flow tools. +**Disable tools to limit capabilities.** Disabled tools cannot be discovered or executed. If you only manage content, disable schema and flow tools to prevent those operations. :: ### Default Settings diff --git a/content/guides/11.ai/1.assistant/4.tips.md b/content/guides/11.ai/1.assistant/4.tips.md index 0465db4b0..ee11e23d3 100644 --- a/content/guides/11.ai/1.assistant/4.tips.md +++ b/content/guides/11.ai/1.assistant/4.tips.md @@ -12,9 +12,11 @@ Follow these tips to work effectively with AI Assistant and get better results f The more specific you are, the better results you'll get. **Less effective:** + > "Add a new post" **More effective:** + > "Create a new article in the articles collection with title 'Getting Started with Directus', status 'draft', and assign it to the 'Tutorials' category" ## Complex Tasks @@ -31,6 +33,7 @@ Break complex requests into smaller, more manageable steps: Long conversations can lose context. When switching to a different task, clear the conversation and start fresh. **Signs you should start a new conversation:** + - The AI seems confused about your schema - Responses are becoming less relevant - You're working on an unrelated task @@ -39,7 +42,7 @@ Long conversations can lose context. When switching to a different task, clear t - Read-only tools like Schema can safely be set to :icon{name="material-symbols:check" class="text-success"} **Always Allowed** - Keep write operations on :icon{name="material-symbols:approval-delegation-outline" class="text-warning"} **Needs Approval** until you're confident -- :icon{name="material-symbols:block-outline" class="text-error"} **Disable** tools you don't need to reduce token usage +- :icon{name="material-symbols:block-outline" class="text-error"} **Disable** tools you don't want the Assistant to discover or run See [Tool Behavior](/guides/ai/assistant/tools#tool-behavior) for more details. @@ -48,6 +51,7 @@ See [Tool Behavior](/guides/ai/assistant/tools#tool-behavior) for more details. Context attachments help the AI understand what you're working with. See [Adding Context](/guides/ai/assistant/usage#adding-context) for setup details. **When to attach context:** + - Asking about or modifying specific items - Comparing or batch-processing content - Making AI-assisted edits in the Visual Editor @@ -57,16 +61,19 @@ Context attachments help the AI understand what you're working with. See [Adding - Sharing audio or video files for transcription or analysis **Keep in mind:** + - Maximum 10 context items per message - Context is captured as a snapshot when sent - Large items increase token usage **Visual Editor tips:** + - Add multiple elements as context before sending a message - Hover context cards to verify you've selected the right elements - Add elements from different pages—context persists while navigating **File attachment tips:** + - Use drag-and-drop for quick uploads from your desktop - Select from the File Library when referencing existing assets - Image files show previews; other types show a file icon @@ -127,7 +134,7 @@ Transcribe this audio recording AI Assistant requires API keys from OpenAI or Anthropic — you cannot use a ChatGPT Plus or Claude Pro subscription. API access is billed per token, so costs scale with usage. Be mindful of this, especially with larger models. ::callout{icon="i-lucide-circle-dollar-sign" color="warning"} -**Disable tools you don't use.** Disabled tools are not loaded into context, reducing token usage and API costs. If you only work with content, disable schema modification tools. +AI Assistant loads system tool details on demand, so unused tools add little to token costs no matter which model provider you use. Disable tools to restrict what the Assistant can do, not to save costs. :: --- @@ -217,23 +224,25 @@ The AI is instructed to ask for confirmation before deleting items. However, LLM ### Related Data May Be Affected When deleting items that have relationships, consider cascade behavior: + - Deleting an author may affect related articles - Deleting a category may orphan products The LLM may not always warn you about potential impacts. - --- ## When AI Assistant Works Best **Great for:** + - Exploring and understanding your schema - Quick content operations (create, update, query) - Setting up new collections and fields - Triggering manual flows **Consider other approaches for:** + - Very large bulk operations (use direct API or import / export through the Data Studio) - Complex data migrations (use scripts or dedicated tools) - Sensitive operations on production data (test in staging first) diff --git a/content/guides/11.ai/2.mcp/1.installation.md b/content/guides/11.ai/2.mcp/1.installation.md index 3d08c7f52..c806a24b9 100644 --- a/content/guides/11.ai/2.mcp/1.installation.md +++ b/content/guides/11.ai/2.mcp/1.installation.md @@ -17,6 +17,64 @@ The Directus MCP server is disabled by default and must be manually enabled. Whe System administrators can completely disable MCP functionality through [configuration environment variables](/configuration/ai#model-context-protocol). +## 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: + +| Mode | Tool discovery | Use it when | +| ------------ | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | +| **Default** | Your MCP client selects from the individual Directus tools | Your client searches or loads tools on demand, or you want per-tool approval controls | +| **Registry** | Directus exposes a small registry that the model searches | Your client loads every tool definition upfront, has a tool-count limit, or spends too much context on unused tools | + +::callout{icon="i-lucide-lightbulb" color="primary" title="Recommendation"} +Use one discovery layer. Prefer the default mode when your client already provides tool search or deferred loading. Otherwise, use registry mode to protect the model's context window. +:: + +### Default Mode + +The default MCP URL exposes each Directus tool separately to the client: + +```text +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](https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search) on supported models, and current versions of [Cursor dynamically load the MCP tools they need](https://cursor.com/blog/dynamic-context-discovery). Custom clients using supported OpenAI models can also [opt into tool search](https://developers.openai.com/api/docs/guides/tools-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](https://code.visualstudio.com/docs/agents/reference/ai-settings) 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`. + +```text +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: + +```text +https://your-directus-url.com/mcp?tool_mode=registry&access_token=your-generated-token +``` + +::callout{icon="i-lucide-triangle-alert" color="warning"} +Do not automatically approve `execute`. It can run both read and write operations, and the client cannot apply the underlying tool's individual approval policy. Use scoped Directus permissions and keep the **Allow Deletes** setting disabled unless you need it. +:: + ## 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. @@ -62,6 +120,7 @@ Read the [MCP OAuth guide](/guides/ai/mcp/oauth) for the full authorization flow Static access tokens work with clients that do not support MCP OAuth. Use a dedicated Directus user when possible. ::callout{icon="i-lucide-user-plus" color="primary" title="Create a dedicated MCP user"} + 1. Navigate to **User Directory**. 2. Click **Create User**. 3. Configure the user: @@ -71,7 +130,7 @@ Static access tokens work with clients that do not support MCP OAuth. Use a dedi 4. Open the user profile. 5. Scroll to the **Token** field and generate a new token. 6. Copy the token, then save the user. -:: + :: ::callout{icon="i-lucide-user" color="warning" title="Use an existing user"} Avoid using your personal admin account for AI operations. If you must use an existing user, open that user profile, generate a token from the **Token** field, copy it, and save the user. @@ -316,22 +375,25 @@ Cursor currently uses Dynamic Client Registration. Once connected, test your setup with a simple question about your Directus instance: -:::chat ---- +## :::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" + +- 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 @@ -339,12 +401,14 @@ messages: 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 @@ -365,13 +429,13 @@ or add the administrator role to your MCP user. 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). | +| 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). | --- diff --git a/content/guides/11.ai/2.mcp/3.tools.md b/content/guides/11.ai/2.mcp/3.tools.md index 31421b344..597d05380 100644 --- a/content/guides/11.ai/2.mcp/3.tools.md +++ b/content/guides/11.ai/2.mcp/3.tools.md @@ -11,7 +11,50 @@ The Directus remote MCP server provides a set of tools that allow AI assistants **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. :: -## Available 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: + +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. + +| 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 | + +::callout{icon="i-lucide-triangle-alert" color="warning"} +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: diff --git a/content/guides/11.ai/2.mcp/5.troubleshooting.md b/content/guides/11.ai/2.mcp/5.troubleshooting.md index 871686dc1..c1ac916a7 100644 --- a/content/guides/11.ai/2.mcp/5.troubleshooting.md +++ b/content/guides/11.ai/2.mcp/5.troubleshooting.md @@ -15,6 +15,12 @@ Check that MCP is enabled in **Settings → AI → Model Context Protocol** and - ✅ `https://your-site.com/mcp` - ❌ `https://your-site.com` +### Only Three Tools Appear + +If your MCP URL contains `tool_mode=registry`, Directus exposes only `search`, `execute`, and `schema`. The AI discovers other Directus tools through `search` and runs them through `execute`. + +Remove `tool_mode=registry` from the URL to expose each Directus tool separately. + ### Authentication Failures 1. Verify your token is generated and saved in Directus diff --git a/content/guides/11.ai/2.mcp/7.security.md b/content/guides/11.ai/2.mcp/7.security.md index 05ee3ca0f..78ebb64f1 100644 --- a/content/guides/11.ai/2.mcp/7.security.md +++ b/content/guides/11.ai/2.mcp/7.security.md @@ -66,6 +66,7 @@ Many AI clients let you automatically approve tool calls without review. This is - Review each tool call before approving, especially delete operations. - Do not enable auto-approval for MCP operations. - Read the tool call details carefully to understand what data will be modified. +- In [registry mode](/guides/ai/mcp/tools#registry-mode), do not automatically approve `execute`. It can run both read and write operations, and the client cannot apply the underlying tool's individual approval policy. --- From 2d3d66c90b3bd7dc918aaa14e284ff6a229936e7 Mon Sep 17 00:00:00 2001 From: bryantgillespie Date: Wed, 19 Aug 2026 14:50:41 -0400 Subject: [PATCH 2/2] Address tool registry review feedback --- content/guides/12.ai/1.assistant/3.tools.md | 2 ++ content/guides/12.ai/2.mcp/1.installation.md | 31 +++++++++----------- 2 files changed, 16 insertions(+), 17 deletions(-) diff --git a/content/guides/12.ai/1.assistant/3.tools.md b/content/guides/12.ai/1.assistant/3.tools.md index 1909327eb..4203fa264 100644 --- a/content/guides/12.ai/1.assistant/3.tools.md +++ b/content/guides/12.ai/1.assistant/3.tools.md @@ -9,6 +9,8 @@ AI Assistant uses tools to perform actions on your behalf. Each tool handles a s AI Assistant discovers system tools on demand: it searches the available tools and loads only the details it needs for the current task. This keeps tool definitions out of the context window until they are needed, leaving more room for your conversation, schema, and results with any model provider. You still configure approvals and availability for each underlying tool individually. +Behind the scenes, the model starts with three root tools: `search` finds relevant tools and loads their details, `execute` runs a discovered tool, and `schema` inspects collections directly. The tool list below shows the underlying Directus tools that `search` can discover and `execute` can run. + ::callout{icon="i-lucide-shield" color="info"} **Tools use your existing user permissions.** Users without admin access won't see Admin Only tools. If you can't access a collection or perform an action in Directus, the AI can't either. :: diff --git a/content/guides/12.ai/2.mcp/1.installation.md b/content/guides/12.ai/2.mcp/1.installation.md index c806a24b9..4d25a09fb 100644 --- a/content/guides/12.ai/2.mcp/1.installation.md +++ b/content/guides/12.ai/2.mcp/1.installation.md @@ -130,7 +130,7 @@ Static access tokens work with clients that do not support MCP OAuth. Use a dedi 4. Open the user profile. 5. Scroll to the **Token** field and generate a new token. 6. Copy the token, then save the user. - :: +:: ::callout{icon="i-lucide-user" color="warning" title="Use an existing user"} Avoid using your personal admin account for AI operations. If you must use an existing user, open that user profile, generate a token from the **Token** field, copy it, and save the user. @@ -375,25 +375,22 @@ Cursor currently uses Dynamic Client Registration. Once connected, test your setup with a simple question about your Directus instance: -## :::chat - +:::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" - + - 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