Always-on health status

MCPBoltBar checks the health of every registered MCP server once per minute and displays a colored dot next to each server. You don't need to trigger a check manually — the status is always current.

What the colors mean

Color	Status	Meaning
Green	Reachable	The server responded successfully to the last health check.
Amber	Degraded	The server responded but with a non-success status, or the response was slow (above the timeout threshold). The server is running but may not be fully functional.
Red	Unreachable	The server did not respond — connection refused, timeout, command not found, or the process exited immediately.
Grey	Not checked	The server is disabled (toggled off) or MCPBoltBar has not run a check yet since launch.

How checks are performed

MCPBolt uses different strategies depending on the server's transport type:

Remote servers (HTTP / SSE)

For servers with a url field, MCPBolt sends an HTTP GET to the server's URL (or a /health endpoint if one is available). A 2xx response means green. A 4xx/5xx or a connection error means red. A slow response (default timeout: 5 seconds) means amber.

If the URL requires an Authorization header (as specified in the config's headers field), MCPBolt includes it in the health check request.

Local servers (stdio)

For servers launched via command + args, MCPBolt spawns the process, sends the MCP initialization handshake, waits for a valid response, then terminates the process. A successful handshake means green. A non-zero exit code, a missing binary, or a timeout means red.

This means health checks briefly spawn local stdio servers. The spawn is kept short — MCPBolt exits after the handshake, not after a full session.

ℹ

Resource impact. Spawning a stdio server once per minute is lightweight for most servers. If a server is slow to start (e.g. a large Python package), it may occasionally appear amber due to the timeout. You can increase the timeout in Settings.

Check interval

Health checks run every 60 seconds while MCPBoltBar is running. There is no way to disable health checks globally, but disabling a server (toggling it off) stops checks for that server.

Interpreting failures

Red — command not installed

The most common cause of red on a stdio server is that the command isn't on your PATH. For example, if the server uses python3 and Python isn't installed, the spawn fails immediately. Install the dependency and the server will turn green on the next check.

Red — network blocked

Remote servers show red if they can't be reached — VPN down, firewall rule, or the service itself is offline. Check connectivity in a browser or with curlbefore assuming the server config is wrong.

Red — wrong URL

If you configured a remote server with an incorrect URL, health checks will always fail. Use the Edit action to correct the URL.

Amber — slow start

Amber often means the server started successfully but took longer than expected. This is common for servers that download dependencies at startup (e.g. npx -y packages on first run). After the first run, subsequent checks are usually green.

💡

Manual re-check. To force an immediate re-check without waiting for the 60-second interval, click the health dot on any server row. MCPBolt runs a single check and updates the status in place.