Troubleshooting

Having trouble with your MCP setup? Here are the most common fixes.

Connection Issues

MCP Server Not Found

Check that MCP is enabled in Settings → AI → Model Context Protocol and your URL includes the /mcp endpoint:

• ✅ 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
2. Check your MCP user has a role assigned
3. Test your token with curl:

curl -H "Authorization: Bearer your-token" \
     https://your-directus-url.com/items/directus_collections

405 Method Not Allowed

The /mcp endpoint only accepts POST requests. Authenticated GET and HEAD requests return 405 Method Not Allowed with an Allow: POST header. Directus does not offer a separate server-sent event stream, so clients that try to open one receive this response. Most MCP clients continue over POST automatically. If yours does not, update it to a version that supports the Streamable HTTP transport.

Permission Errors

Access Denied / Forbidden (403) Errors

Your MCP user needs appropriate permissions:

• Content operations: Read/write access to target collections
• Schema operations: Administrator role required

Delete Operations Blocked

Enable "Allow Deletes" in Settings → AI → Model Context Protocol even if your user has delete permissions.

Client Issues

Claude AI

• Check that your Directus instance is publicly accessible because Claude Custom Connectors require a public URL. You can use a tool like ngrok or untun to create a temporary public URL.
• Ensure that you're URL is properly formatted and the token is included in the URL (e.g. https://your-directus-url.com/mcp?access_token=your-generated-token)
• Perform a hard refresh of your browser (⌘ + Shift + R or Ctrl + Shift + R) to ensure that the latest configuration is loaded.

Cursor

• Ensure that you have placed .cursor/mcp.json in your project root
• Check the JSON syntax for MCP configuration

Quick Debugging

Test with simple operations:

1. "Please call the system prompt tool"
2. "What collections do I have?"
3. "Show me one item from collection-name"