# Troubleshooting

> Common issues and solutions when setting up and using the Directus MCP server.

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:

```bash
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](https://ngrok.com/) or [untun](https://github.com/unjs/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 <span>

collection-name

</span>

"