Skip to content
Wayland Docs

MCP Server Issues

When an MCP server does not connect or its tools do not appear, the cause is usually the launch command, the transport, or a name collision. Work through these in order.

The server fails to launch (stdio)

Section titled “The server fails to launch (stdio)”

For a stdio server, Wayland runs a command and talks to it over standard input and output. If it fails to start:

  • Confirm the command is on your PATH, or use an absolute path.
  • Check the args array: each argument is a separate string, not one space-joined string.
  • Run the same command yourself in a terminal. If it errors there, fix that first.
  • Pass any required environment variables through the server’s env block, not your shell.

The handshake times out

Section titled “The handshake times out”

If the process starts but never registers tools, the startup handshake did not complete:

  • The server may be writing logs to stdout, which corrupts the stdio protocol. Configure it to log to stderr or a file.
  • For SSE or streamable-http servers, confirm the URL is reachable and returns the expected stream. A proxy or firewall between Wayland and the server will block the handshake.

Tools do not appear

Section titled “Tools do not appear”
  • If the server connected but you do not see its tools, it may have registered zero tools, or they are deferred. A deferred server loads tool schemas on demand: the agent finds them through ToolSearch rather than at startup.
  • In the desktop app, confirm the server is synced to the assistant you are using. A server installed but not synced to that assistant contributes no tools to it.

Tool name collisions

Section titled “Tool name collisions”

When two servers expose a tool with the same name, Wayland auto-prefixes them as mcp__{server}__{tool} so both stay reachable. If a tool you expected by its short name is not found, look for the prefixed form.

Where to look next

Section titled “Where to look next”

Next

Section titled “Next”