Troubleshoot MCP Connections

Troubleshoot MCP Connections

An MCP connection can fail before a tool appears, while a tool is running, or after a result is returned.

The cause may involve:

• the server endpoint;
• authentication;
• the network;
• the server process;
• tool discovery;
• the selected AI model;
• required input;
• permissions;
• the connected service;
• the workflow; or
• the destination of a write action.

Begin by identifying the exact symptom.

Then check one layer at a time.

Start with the visible symptom

Use the symptom to choose the first check.

Symptom	First check
Server unavailable	Endpoint, server process, network, and authentication
Authentication failed	Credential, account, permission, and expiry
Tools do not appear	Connection state, tool discovery, refresh, and model support
Model does not call the tool	Tool selection, instruction, and model capability
Wrong tool is called	Enabled tool list and instruction clarity
Tool call fails	Activity log, required input, permission, and service state
Result is empty	Search input, filters, source content, and no-match handling
Result is incorrect	Tool input, source, returned data, and model interpretation
Write action is missing	Tool result, destination, and external service
Duplicate action appears	Retries, overlapping runs, and delayed confirmation

Avoid changing the endpoint, credential, model, workflow, and permissions at the same time.

Change one thing, then test again.

Confirm which server is involved

Feluda may use:

• its built-in MCP server;
• one or more external MCP servers;
• tools supplied through installed Genes; and
• other connected tool sources.

Before troubleshooting, identify:

• the server name;
• whether it is built-in or external;
• the tool name;
• where the tool appears;
• whether the task ran in Workbench or a workflow; and
• whether the tool reads or writes information.

Clear server and tool names make troubleshooting easier.

Open the MCP Servers page

Select MCP Servers from the Feluda sidebar.

Find the affected connection.

Review:

• the connection name;
• the endpoint URL;
• the current state;
• authentication requirements;
• visible warnings;
• available tools; and
• any recent configuration changes.

Read the full error before editing the connection.

If the server is unavailable

Check whether:

• the server process is running;
• the endpoint URL is correct;
• the expected port is open;
• the server path is correct;
• the computer or remote host is available;
• the network connection works;
• a firewall blocks the request;
• a proxy or VPN changes access; and
• the remote service is experiencing an outage.

For a local server, open or restart the application that provides it.

For a remote server, confirm its status with the server owner.

Check the endpoint URL

Compare the saved endpoint with the official connection details.

Review:

• http or https;
• server name or IP address;
• port number;
• path;
• spelling;
• capitalisation where relevant;
• trailing slash requirements; and
• spaces copied before or after the URL.

Do not guess a different endpoint.

Use the value supplied by the server owner or your organisation.

Local endpoint problems

A local endpoint may fail because:

• the server application is closed;
• the process stopped;
• the port changed;
• another application uses the port;
• the service starts only after sign-in;
• the operating system restarted;
• a local firewall blocks it; or
• the endpoint was copied incorrectly.

Start the local service and test the connection again.

Keep it running while Workbench or a workflow uses its tools.

Remote endpoint problems

A remote endpoint may fail because:

• the internet connection is unavailable;
• the remote host is offline;
• the server address changed;
• the service requires a VPN;
• a firewall blocks the destination;
• authentication expired;
• a certificate problem occurred; or
• the provider temporarily disabled the service.

Confirm network requirements with the server owner.

Do not disable normal security controls only to make the connection work.

If authentication fails

Review:

• the credential type;
• the account;
• the token or key;
• whether it was copied completely;
• whether it belongs to the correct server;
• whether it expired;
• whether the account is active;
• whether the required permission is included; and
• whether the server changed its authentication method.

Update authentication only in the protected connection settings.

Do not paste private credentials into Workbench or workflow input.

If authentication worked before

A previously working credential may stop working because:

• it expired;
• it was revoked;
• the user account changed;
• the service rotated keys;
• permissions were reduced;
• the server moved;
• the organisation changed authentication policy; or
• the protected value was replaced incorrectly.

Confirm the current credential requirements with the server owner.

Pause dependent workflows and schedules until the connection is restored.

Protect credentials during troubleshooting

Never place:

• passwords;
• API keys;
• access tokens;
• private headers;
• client secrets; or
• connection credentials

into a conversation, Journal entry, workflow prompt, or support screenshot.

Store them only in the intended protected settings.

When sharing an error, remove private values first.

If the connection saves but tools do not appear

Confirm that:

• the server is reachable;
• authentication completed;
• the server exposes compatible tools;
• the connection finished discovering them;
• Feluda refreshed the tool list;
• Workbench or Studio was reopened when needed;
• the correct server is selected; and
• the selected model supports tool use.

A server connection can be available without exposing the tool you expected.

Review the server's documented tool list.

Refresh the tool list

After adding or updating a server:

• save the connection;
• wait for discovery to complete;
• reopen the Tools selector;
• refresh or reopen Workbench;
• reopen the Studio block when needed; and
• confirm the connection state again.

If the tools still do not appear, test whether the server is actually returning a compatible tool list.

If only some tools appear

Some tools may be hidden or unavailable because:

• the server no longer provides them;
• the account lacks permission;
• the server version changed;
• the selected model cannot use them;
• a tool is disabled;
• a Gene is not installed or synced; or
• the connection did not refresh fully.

Compare the visible list with the current server documentation.

Do not assume an older tool remains available.

If tools appear in Workbench but not Studio

Check that:

• the Studio LLM block uses a tool-capable model;
• the correct provider and model are selected;
• the block's tool selector has refreshed;
• the workflow was reopened after the connection changed;
• the tool is supported in that context; and
• the MCP server remains available.

Save and reopen the flow after correcting the block settings.

If tools appear in Studio but not Workbench

Check:

• the current Workbench provider and model;
• the Tools selector;
• whether the tool was disabled for the session;
• whether a new conversation is needed;
• whether the server connection remains active; and
• whether the Workbench tool list has refreshed.

Start a new conversation for a clean test.

If the model does not call the tool

Confirm that:

• the tool is enabled;
• the selected model supports tool use;
• the instruction clearly requires current or external information;
• the exact tool name is used when needed;
• unrelated tools are disabled;
• the conversation does not contain conflicting instructions; and
• the task matches the tool description.

Use a direct instruction:

Use the enabled Internal Knowledge Search tool.
Do not answer from memory.

Then review the Activity log.

If the model answers without the tool

The model may believe it can answer from conversation context.

To require the tool, explain:

• which source must be checked;
• that the answer must use returned information;
• what source details must be included; and
• that no answer should be invented when the tool returns nothing.

For example:

Use the enabled record-search tool.

Return only information from the tool result.
If no record is found, write "No matching record found."

If the wrong tool is called

Disable unrelated tools.

Review tools with similar names.

Then give a direct limit:

Use only the enabled customer-record search tool.
Do not call create, update, delete, messaging, or file-writing tools.

Start a new Workbench conversation if older context may be influencing the model.

If the same tool is called repeatedly

Repeated calls may be caused by:

• an unclear instruction;
• incomplete tool output;
• the model not recognising success;
• an empty result;
• a tool error;
• several similar enabled tools;
• a workflow loop; or
• an output format the next step cannot understand.

Stop the task when repeated calls could create unwanted actions.

Test one tool with one short instruction.

Use the Activity log

In Workbench, open Activity after the tool task.

Review:

• tool name;
• input parameters;
• output data;
• completion state;
• warnings;
• errors; and
• repeated calls.

This helps separate:

• a model problem;
• a tool-input problem;
• a server problem; and
• a final-answer problem.

Do not rely only on the conversational response.

Use RunFlows output

For a workflow, open its RunFlows result.

Review:

• the starting input;
• intermediate output;
• the tool call;
• the returned result;
• the selected branch;
• errors;
• warnings; and
• the final output.

Add an Emit block in Studio when the raw MCP result needs to be visible before later processing.

Find the first failing step

Trace the task in order.

Ask:

1. Did Feluda reach the server?
2. Did authentication succeed?
3. Did the tool appear?
4. Did the model call the correct tool?
5. Did the tool receive the expected input?
6. Did the server return a result?
7. Did the model interpret it correctly?
8. Did a write action reach the destination?

Correct the first unexpected step.

If required input is missing

The tool may require:

• a record identifier;
• a search term;
• a filename;
• a date;
• a destination;
• an account;
• structured fields; or
• another required value.

Review the tool description and Activity input.

Update the instruction or earlier workflow block so the required value is provided clearly.

If the tool rejects the input

Check whether:

• the value uses the expected format;
• the identifier is complete;
• the date format is valid;
• the filename or path exists;
• the destination is supported;
• a required field is empty;
• an unsupported action was requested; or
• the input is too large.

Test with the smallest valid example supplied by the server owner.

If a permission error appears

Review the relevant permission controls.

Depending on the tool, this may involve:

• URL rules;
• IP rules;
• file-path rules;
• port rules;
• account permissions;
• record access;
• read or write access; or
• connected-service policy.

Confirm that the source or destination is correct before changing access.

Do not expand permissions more broadly than the task requires.

Flow permission problems

A workflow tool may fail when its required destination is not permitted.

Review the flow's Permissions panel.

Check the applicable:

• URL allowlist or denylist;
• IP allowlist or denylist;
• path allowlist or denylist;
• port allowlist or denylist; and
• other visible restrictions.

Update only the rule needed for the approved task.

Test the workflow again with a safe example.

If a read tool returns no result

A no-match result is different from a failed call.

Check:

• spelling;
• identifier format;
• search filters;
• date range;
• selected source;
• account access;
• source availability; and
• whether the record actually exists.

The model should report the empty result clearly.

It should not invent matching information.

If the tool returns incomplete data

Review:

• the requested fields;
• the tool input;
• available account permissions;
• applied filters;
• source completeness;
• result limits;
• pagination when supported; and
• whether the model omitted part of the result.

Compare the raw Activity output with the final answer.

The server may have returned more information than the model included.

If the result is incorrect

Determine where the error first appears.

The problem may be:

• wrong tool input;
• wrong source;
• outdated source data;
• incorrect filters;
• incomplete tool output;
• model misinterpretation;
• an earlier workflow transformation; or
• final formatting.

Ask the model to separate the raw returned values from its summary.

If dates or amounts change

Compare the exact returned data with the final answer.

Check whether:

• the source uses another timezone;
• date formatting changed;
• decimal separators differ;
• currency was converted;
• the model rounded a value;
• an earlier block transformed the field; or
• the wrong record was selected.

Preserve source values when accuracy is important.

If the server returns an unexpected format

A server update may change its tool result.

Review:

• field names;
• nesting;
• missing fields;
• new fields;
• date and number formats;
• error structure; and
• whether the workflow expects an older format.

Update dependent workflows only after confirming the new server behaviour.

Pause schedules that rely on the old format.

If a write action fails

Check:

• the destination;
• required fields;
• account permission;
• record state;
• file path;
• message recipient;
• action type;
• server availability; and
• returned error.

Test with a safe destination or approved test environment.

Keep high-impact actions behind human review.

If a write action reports success but nothing changed

Inspect the external destination.

Confirm:

• the correct account;
• the correct record;
• the correct file;
• the correct recipient;
• the correct workspace;
• the action timestamp; and
• whether the service delayed the update.

The model's statement is not proof that the external action completed.

If a write action completes in the wrong place

Stop related workflows and pause schedules.

Review:

• destination parameters;
• account selection;
• record identifiers;
• file paths;
• recipient values;
• values passed from earlier blocks; and
• whether the wrong server or tool was enabled.

Correct and test with non-sensitive information.

Avoid duplicate write actions

A timeout or delayed confirmation can make a completed action look like a failure.

Before retrying:

1. review Activity or RunFlows output;
2. inspect the destination;
3. compare timestamps;
4. confirm whether the item already exists; and
5. retry only when the first action did not complete.

This prevents duplicate files, records, tasks, messages, or notes.

If the call times out

Review:

• server availability;
• network quality;
• request size;
• tool complexity;
• external service state;
• local computer load;
• simultaneous workflows;
• runtime limits; and
• whether a write action completed.

Test a smaller read-only request.

Do not increase runtime limits only to hide a broken service.

If the connection works intermittently

Record when failures occur.

Compare:

• time of day;
• network;
• VPN state;
• server process;
• authentication age;
• other active workflows;
• request size;
• remote service status; and
• local resource use.

Intermittent problems often require several observations rather than one configuration change.

If Workbench works but the workflow fails

Compare the two environments.

Check whether the workflow uses:

• the same model;
• the same tool;
• the same instruction;
• the same input;
• the same server;
• the same permission rules;
• the same authentication; and
• the same output expectations.

Add Emit blocks to inspect what the workflow passes to the tool.

If the workflow works manually but fails on schedule

Check whether, at the scheduled time:

• Feluda was available;
• the computer was awake;
• the server process was running;
• the network or VPN was available;
• authentication was valid;
• the external service was online;
• the source existed;
• another run caused a conflict; and
• the schedule supplied the expected input.

Pause the schedule until a manual test succeeds again.

If a local server works only after restart

Review whether:

• the server starts automatically;
• the process stops after inactivity;
• the port changes;
• the computer sleeps;
• the operating system restarts;
• another application takes the port; or
• the service needs manual sign-in.

For scheduled use, make sure the local server remains available at the trigger time.

If a remote server requires VPN access

Confirm that:

• the VPN is connected;
• the correct network profile is active;
• the server is reachable through that VPN;
• authentication still works;
• the computer does not disconnect during sleep; and
• scheduled runs occur while access is available.

Do not route sensitive data through an unapproved network.

Compare models

Different models may call the same tool differently.

To compare them:

1. start a new conversation for each model;
2. enable the same tool;
3. use the same instruction;
4. use the same sample input;
5. review each Activity log; and
6. compare tool choice, parameters, output handling, and errors.

Choose the model that performs the complete task reliably.

Reconnect after a server update

When the server owner changes the endpoint, authentication, or tools:

1. identify dependent workflows;
2. pause related schedules;
3. update the MCP connection;
4. confirm tool discovery;
5. test one read-only tool;
6. review Activity;
7. test required write actions safely;
8. retest dependent workflows; and
9. resume schedules only after successful results.

Do not assume the old workflow remains compatible.

If the server is no longer trusted

Stop using its tools.

Pause dependent schedules and workflows.

Review:

• what information was sent;
• what permissions were granted;
• whether credentials should be revoked;
• whether another approved server is available; and
• whether any external records need review.

Remove the connection only after identifying what depends on it.

Remove and reconnect only when justified

Removing and recreating a connection can help after a confirmed configuration problem.

Before doing so, record:

• the server name;
• endpoint;
• authentication method;
• dependent workflows;
• scheduled uses; and
• tool names.

Reconnect with the official current settings.

Then repeat the read-only test before restoring workflows.

Use a small repeatable test

Keep one safe test for the connection.

For example:

Use the enabled knowledge-search tool to search for
"MCP connection test".

Return the tool result and any error.
Do not create or change anything.

Reuse the same test after endpoint, authentication, server, or Feluda changes.

Change one thing at a time

Change only one of these before retesting:

• endpoint;
• authentication;
• network;
• server process;
• model;
• tool selection;
• instruction;
• permission;
• input; or
• workflow connection.

This helps identify the real cause.

Pause automation while troubleshooting

Pause related schedules when:

• authentication fails;
• the server is unavailable;
• tools disappear;
• write actions use the wrong destination;
• duplicates occur;
• permissions are unclear;
• results become unreliable; or
• repeated timeouts appear.

Resume only after successful manual tests.

A practical troubleshooting routine

Use this process:

1. Identify the server and tool.
2. Define the exact symptom.
3. Review the MCP Servers connection state.
4. Check endpoint, network, and server process.
5. Confirm authentication.
6. Confirm the tool appears.
7. Test one read-only action in Workbench.
8. Review the Activity log.
9. Check required input and permissions.
10. Compare raw tool output with the final answer.
11. Confirm write actions at their destination.
12. Test the affected workflow in RunFlows.
13. Check scheduled availability when relevant.
14. Change one item.
15. Repeat the same safe test.
16. Resume automation only when the connection is dependable.

This approach separates connection, tool, model, workflow, and destination problems without creating unnecessary changes.