Troubleshooting

Common issues with tools and MCP servers, and how to read what Kerlig tells you.

A local server shows "Starting…" and then fails

The red text under the status is the server's own error output. Read it first, it usually names the problem. Common causes:

• Arguments in the wrong shape. Arguments are space- or line-separated. Quote any single argument that contains spaces.
• The command isn't installed. The command must work in your terminal (npx, uvx, a binary path). Kerlig uses your login shell's PATH, so if it runs in Terminal, it runs in Kerlig.
• A missing API key. Many servers exit immediately without their environment variables. Check the server's documentation for required keys.

A remote server shows "Needs sign-in"

The OAuth session expired or was revoked. Open the server in Settings → MCP and click Connect to sign in again.

The AI doesn't use a tool I expected

• Check the server's status dot is green and the specific tool is enabled.
• Check the tool's policy isn't Deny. Denied tools are never offered to the model.
• Check the action allows tools. By default only Ask does (see approvals and permissions).
• Check the model. If the input area shows "Tools off for this model", pick a model that supports tool calling.
• Kerlig offers at most 60 MCP tools per request. With many servers connected, disable tools you don't use.

An answer stops mid-way with tool activity showing

A run performs at most 10 tool steps before answering with what it has. If a tool fails, the AI is told and continues. Failed calls are marked in the tool activity line under the answer, where you can expand each call to see its result.