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

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

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"