A backend is in Error
BinaryMissingInstall the binary at its path; a watched backend retries by itselfSpawnFailedMake the path an executable regular fileInitTimeoutFind why startup hangs, or raise MCP_TOOLING_INIT_TIMEOUTInitFailedRead the backend's stderr and correct its configurationBinaryMissingSpawnFailedInitTimeoutMCP_TOOLING_INIT_TIMEOUTInitFailedRead stderr with mcp_registry_logs, then reload:
{ "name": "mcp_registry_reload", "arguments": { "name": "git" } }A backend is in NeedsAuth
The remote server refused the credential, and no reconnect runs until one arrives. Authorize with mcp-registry cli auth login <name> or the mcp_registry_auth_login tool; the backend starts as soon as the credential lands. Run the CLI as the account the server runs under, since credentials live in that account's home directory under ~/.mait/mcp/registry/oauth/.
Login fails or waits
A missing discovery pointer means the url names the wrong endpoint; the message names the right one. If port 47822 is in use, finish the other login or set "callback": {"explicit": "<address>:<port>"}. Host mode is written {"host": {"host": "…", "port": 47822}}; a flat host and port object rejects the registry file. From a container on macOS or Windows, publish the callback port. When no browser opens, open the printed URL yourself. If completion says no authorization is in progress, start the login again.
Connected, but every tool call is rejected
Some servers accept the handshake with any token and refuse later requests, so the backend shows Connected, possibly with no tools, or keeps reconnecting when the server also refuses the registry's liveness check and tool listing. It never waits in NeedsAuth, so a CLI login does not restart it. Authorize again with the mcp_registry_auth_login tool, or log in from the CLI and then reload the backend. For a static header, fix the variable and restart the registry. An expired status without a refresh token needs new consent.
An unset variable or a rotated credential
A ${VAR} reference with no value stops startup; export it or write a fallback such as ${VAR:-}. References resolve from the running server's environment, so restart it after rotating a value. An export omits headers; add them back with ${VAR} references.
A backend keeps reconnecting or pauses
Reconnecting(N) backs off from 1 to 30 seconds and settles when the backend returns. After five failures in ten seconds, restarts pause for 30 seconds. If N keeps climbing, treat it as the matching error kind, fix the cause and reload.
Tools, notifications or skills do not reach the client
Check the backend is Connected with mcp_registry_list, then find the tool with mcp_registry_tool_search and enable it with mcp_registry_tool_enable; reconnect a client that caches its tool list. Set unaddressed to broadcast on the backend (the older relay_notifications: true maps to it) and reload to forward a backend's own notifications that name no recipient. Skills need a backend that declares them and a registry at 0.7.0 or later.
Logs, saved resources, the pool or stdio
mcp_registry_logs covers stdio backends; use a socket or HTTP backend's own logs. Save resources with a URI from resources/list and an absolute, writable path. A pool-exhausted error can come from a stalled call: inspect, then reload. For stdio, keep stderr out of stdout and leave MAIT_LOG_FORMAT unset.
What you getEvery backend connected, authorized and offering its tools to your session.