Troubleshooting

Most MCP problems come from one of these causes:

• The integration is disabled
• The tool is disabled
• The server is not connecting
• A required permission was denied
• The runtime or environment is missing

First Checks

First of all, ensure you are running a model that is capable of using MCP tools. Then start with the smallest possible test.

1. Confirm the integration is enabled in Settings → Integrations
2. Confirm the exact tool you need is enabled and verify it's approval setting
3. Reconnect the integration
4. Test with a very small request

Small requests are better for debugging than large actions.

Examples:

• "List my reminder lists"
• "Calculate this folder size"

Permissions

Some integrations need macOS permission before they can work.

Common cases:

• Calendar
• Reminders
• Notes
• Location
• Browser Automation through Apple Events

For browser-related workflows, also confirm Allow JavaScript from Apple Events in the browser if richer context or browser automation is expected.

If Fluent itself is not reacting properly to hotkeys or selected text, also check Accessibility.

Local Servers

If a local external server does not connect, check the launch configuration first.

Most failures come from:

• Wrong command
• Wrong arguments
• Missing environment variables
• Missing runtime such as npx or uvx

If the server starts and exits immediately, open the integration logs.

Remote Servers

If the server is remote, treat it as a connection problem first.

Check:

• Server URL
• Server availability
• Tokens or credentials
• Environment variables
• SSL settings for trusted local or internal endpoints

If you are using OpenAPI mode, keep in mind that it is currently the most experimental path.

Connected But No Tools

If the integration connects but tools do not appear, reconnect once and then inspect the status and logs in the integration editor.

If the tools are visible but Fluent still does not use them, make the request more explicit.

For example:

• "Use Reminders to create tasks from this"
• "Use Web Search to compare these products"
• "Read this folder and tell me how many images are in it"

Too Many Tools

If a model chooses the wrong tool or behaves inconsistently, reduce the available tool set.

Disable integrations and/or tools that are unrelated to the task. Also check whether the workflow is waiting for approval rather than failing.