Skip to content

Learn · Track

Troubleshooting MCP and agents

One page per error message. Each says what the message means according to the specification or the runtime, which side causes it, how to confirm the cause, and how to fix it. Start from the exact text you see: connection closed, ENOENT, session not found, method not found, invalid params, invalid_client, insufficient_scope, timeouts, missing tools and agents that loop.

Guides in this track

Intermediate16 guides, in reading order

  1. -32000 Connection closed

    Why an MCP client reports -32000 Connection closed: the stdio server exited, never started or broke its stdout channel. How to find the cause and fix it.

    7 min read

  2. spawn npx ENOENT

    The MCP client could not find npx, uvx or node on the PATH it launches servers with. Why it works in your terminal but not in the app, and how to fix it.

    6 min read

  3. Env vars not passed

    Why a local MCP server reports a missing token: the variable was never passed, the client builds a short environment, or a placeholder was not expanded.

    6 min read

  4. Server shows no tools

    The MCP server starts and connects, yet the agent sees no tools. Check the tools capability, listing errors, pagination, filters, policies and names.

    7 min read

  5. Session not found (404)

    A Streamable HTTP MCP server answered 404 for an Mcp-Session-Id it no longer knows. Why it happens after restarts and scale-out, and how a client recovers.

    7 min read

  6. Request timed out

    Why MCP tool calls time out, what -32001 does and does not mean, how cancellation and progress work, and when a retry is safe or could act twice.

    7 min read

  7. Unsupported protocol version

    What happens when an MCP client and server speak different protocol revisions: the -32020 to -32022 errors of 2026-07-28, older 400 answers, and fixes.

    6 min read

  8. -32601 Method not found

    Why an MCP server or client answers -32601 Method not found: a typo, a capability it never offered or a revision mismatch, and how to check.

    5 min read

  9. -32602 Invalid params

    What MCP error -32602 means, why models send tool arguments a JSON Schema rejects or call a tool that does not exist, and how to make calls validate.

    7 min read

  10. Tool result too large

    Why an MCP tool response exceeds the allowed tokens or fills the context window, and how to fix it on the server, in the client and in the agent.

    7 min read

  11. Path outside allowed directories

    Why the reference filesystem MCP server refuses a path: allowed directories, roots from the client, relative paths, symlinks and containers. Safe fixes.

    6 min read

  12. OAuth invalid_client

    Why connecting a remote MCP server fails with invalid_client: a stale registered client id, no dynamic registration, a redirect URI mismatch or wrong auth.

    8 min read

  13. Authorization metadata

    The MCP client could not discover where to sign in. How OAuth metadata is found, and the path, issuer, redirect and TLS problems that break it.

    7 min read

  14. 403 insufficient_scope

    A remote MCP server accepted your token but refused a tool with 403 insufficient_scope. How to read the challenge and fix it with step-up authorization.

    7 min read

  15. Model won't call tools

    The model answers in text instead of calling a tool. Check what was sent, tool support, tool choice, descriptions, tool count and the prompt, in order.

    6 min read

  16. Agent stuck in a tool loop

    Why an agent repeats one tool call until it hits max iterations: errors it cannot act on, results it cannot use, no stop rule. How to break the loop.

    7 min read

Before and after

Prerequisites: none, though the pages assume you know what an MCP server is. MCP transports and MCP authorization explain the mechanisms most of these errors come from.

Not here? Common issues covers problems with L2M itself: setup, webhooks, templates and parsers. To start from a working agent instead, import one from the recipes.

This website (not the L2M product) uses Google Analytics, only after you accept cookies. Cookie settings