Team "Acme Corp" installs Filesystem MCP with 3 members:
- Alice's instance: status = 'online' (tools available to Alice)
- Bob's instance: status = 'awaiting_user_config' (tools NOT available to Bob)
- Charlie's instance: status = 'offline' (tools NOT available to Charlie)

Each member sees different tool availability based on their instance status.

provisioning
    ↓
command_received (satellite received configure command)
    ↓
connecting (spawning MCP server process or connecting to HTTP/SSE)
    ↓
discovering_tools (calling tools/list)
    ↓
syncing_tools (sending tools to backend)
    ↓
online (ready for use)

awaiting_user_config
    ↓
[User configures personal settings via dashboard]
    ↓
provisioning (backend updates status, sends satellite command)
    ↓
command_received
    ↓
connecting
    ↓
discovering_tools
    ↓
syncing_tools
    ↓
online

online
    ↓
restarting (user updated config, backend sets status immediately)
    ↓
connecting (satellite receives command, restarts server)
    ↓
discovering_tools
    ↓
online

online
    ↓
offline/error (server unreachable or error response)
    ↓
[automatic recovery when server comes back]
    ↓
connecting
    ↓
discovering_tools
    ↓
online

online
    ↓
requires_reauth (401/403 response or token refresh failed)
    ↓
[user re-authenticates via dashboard]
    ↓
connecting
    ↓
discovering_tools
    ↓
online

online
    ↓
(stdio process crashes)
    ↓
connecting (auto-restart attempt 1)
    ↓
(crashes again within 5 minutes)
    ↓
connecting (auto-restart attempt 2)
    ↓
(crashes again within 5 minutes)
    ↓
permanently_failed (manual intervention required)

// services/satellite/src/services/unified-tool-discovery-manager.ts

export type ServerAvailabilityStatus =
  | 'online'
  | 'offline'
  | 'error'
  | 'requires_reauth'
  | 'permanently_failed'
  | 'connecting'
  | 'discovering_tools';

export interface ServerStatusEntry {
  status: ServerAvailabilityStatus;
  lastUpdated: Date;
  message?: string;
}

class UnifiedToolDiscoveryManager {
  private serverStatus: Map<string, ServerStatusEntry> = new Map();

  // Set server status (called by discovery managers and MCP wrapper)
  setServerStatus(serverSlug: string, status: ServerAvailabilityStatus, message?: string): void {
    this.serverStatus.set(serverSlug, {
      status,
      lastUpdated: new Date(),
      message
    });
  }

  // Check if server is available for tool execution
  isServerAvailable(serverSlug: string): boolean {
    const statusEntry = this.serverStatus.get(serverSlug);
    if (!statusEntry) return true; // Unknown = available (safe default)
    return statusEntry.status === 'online';
  }

  // Get all tools, filtered by server status
  getAllTools(): ToolMetadata[] {
    const allTools = this.getAllToolsUnfiltered();
    return allTools.filter(tool => {
      const serverSlug = tool.tool_path.split(':')[0];
      return this.isServerAvailable(serverSlug);
    });
  }
}

// services/satellite/src/services/remote-tool-discovery-manager.ts

// On successful discovery
this.statusCallback?.(serverSlug, 'online');

// On connection error
const { status, message } = RemoteToolDiscoveryManager.getStatusFromError(error);
this.statusCallback?.(serverSlug, status, message);

// services/satellite/src/services/stdio-tool-discovery-manager.ts

// On successful discovery
this.statusCallback?.(processId, 'online');

// On discovery error
this.statusCallback?.(processId, 'error', errorMessage);

Team "Acme Corp" - Context7 MCP Server:
- Alice's instance: status = 'online'
  → Alice sees Context7 tools in discover_mcp_tools

- Bob's instance: status = 'awaiting_user_config'
  → Bob sees NO Context7 tools (must configure API key first)

- Charlie's instance: status = 'offline'
  → Charlie sees NO Context7 tools (server unreachable)

// UnifiedToolDiscoveryManager.getAllTools() filters by user's instance status
const tools = toolDiscoveryManager.getAllTools(); // Only user's 'online' instances

// Tools from user's offline/error/requires_reauth/awaiting_user_config instances are hidden

// services/satellite/src/core/mcp-server-wrapper.ts

const serverSlug = toolPath.split(':')[0];
const statusEntry = this.toolDiscoveryManager?.getServerStatus(serverSlug);

// Block execution for non-recoverable states
if (statusEntry?.status === 'requires_reauth') {
  return {
    error: `Tool cannot be executed - your instance requires re-authentication.

Status: ${statusEntry.status}
Your instance requires re-authentication. Please re-authorize in the dashboard.

Unavailable server: ${serverSlug}`
  };
}

// Allow execution for offline/error (enables recovery detection)

{
  "event": "mcp.server.status_changed",
  "installation_id": "uuid",
  "team_id": "uuid",
  "user_id": "uuid",
  "status": "online",
  "status_message": "Server is online and ready"
}