Fix MCP Server Issues

MCP issues can happen at install time, tool discovery time, binding time, or permission time.

Work from global to per-agent: MCP Library first, then the agent's MCP Servers tab.

Server Not Installed

Open Settings > MCP Library.

If the server is missing, install it first. A server must exist globally before an agent can bind to it.

Install Failed

Open the server in MCP Library and read the install error.

Common causes include:

• Missing package or runtime dependency.
• Invalid server configuration.
• Invalid credentials.
• Docker or runtime not ready.
• Network access failure during install.

Use repair or reinstall actions when available after fixing the cause.

Tools Not Discovered

If the server installs but no tools appear:

• Refresh the MCP Library.
• Wait for lifecycle jobs to finish.
• Check install or discovery errors.
• Repair the server if discovery failed.

Then refresh the agent's MCP Servers tab.

Server Not Available To Agent

Open the agent, then Config > MCP Servers.

Check:

• The server binding is enabled.
• MCP Runtime Health is ready.
• External MCP Tools capability is enabled.
• The binding is not excluded from runtime.
• The server has discovered tools.

Tool Is Blocked

Expand the binding and check the tool policy:

• Allow runs automatically.
• Ask prompts before the tool call.
• Deny blocks the tool.

If the tool is Deny, change it only if the agent really needs it.

Tool Keeps Prompting

If Ask is too noisy, move only the specific low-risk tool to Allow after reviewing real requests.

Do not set all tools to Allow unless the server is low-risk and the agent is tightly scoped.

Auth Or Secret Issues

Check MCP Library secrets and per-agent secret overrides.

Use separate secrets for test and production agents when possible.

Still Failing

Collect:

• MCP server name.
• Install status.
• Runtime state.
• Binding state.
• Tool policy.
• Install error text, if present.
• Whether the issue affects one agent or all agents.