Feature/Bug: Self-hosted satellite URL (DEPLOYSTACK_SATELLITE_URL) not stored or used in client configuration

[bytefrostdev]

Environment

• DeployStack Version: Latest (as of Dec 6, 2025)
• Deployment Method: Docker Compose (self-hosted)
• All Components: Backend, Frontend, Satellite

Description

When self-hosting DeployStack with a custom satellite URL via the DEPLOYSTACK_SATELLITE_URL environment variable, the URL is not persisted in the database and is not used when generating MCP client configurations. The "Get Client Configuration" modal always displays the hardcoded cloud URL (satellite.deploystack.io) regardless of the self-hosted satellite's actual URL.

Current Database Schema

The satellites table has no column to store the satellite's public URL:

\d satellites
                             Table "public.satellites"
     Column     |           Type           | Collation | Nullable |    Default     
----------------+--------------------------+-----------+----------+----------------
 id             | text                     |           | not null | 
 name           | text                     |           | not null | 
 satellite_type | text                     |           | not null | 
 team_id        | text                     |           |          | 
 status         | text                     |           | not null | 'active'::text
 capabilities   | text                     |           | not null | 
 api_key_hash   | text                     |           | not null | 
 last_heartbeat | timestamp with time zone |           |          | 
 system_info    | text                     |           |          | 
 config         | text                     |           |          | 
 created_by     | text                     |           | not null | 
 created_at     | timestamp with time zone |           | not null | now()
 updated_at     | timestamp with time zone |           | not null | now()

Note: No public_url, mcp_endpoint_url, or similar field exists.

Observed Behavior

1. User configures satellite with custom URL:

   environment:
     - DEPLOYSTACK_SATELLITE_URL=https://deploystack.mcp.example.com

2. Satellite starts and registers successfully

3. User clicks "Get Client Configuration" in the UI

4. Modal displays hardcoded cloud URL instead of self-hosted URL:

   {
     "mcpServers": {
       "deploystack": {
         "url": "https://satellite.deploystack.io/mcp",
         "type": "http"
       }
     }
   }

5. Self-hosted users must manually construct the correct configuration:

   {
     "mcpServers": {
       "deploystack": {
         "url": "https://deploystack.mcp.example.com/mcp",
         "type": "http"
       }
     }
   }

Expected Behavior

1. Satellite reports its DEPLOYSTACK_SATELLITE_URL to backend during registration or heartbeat
2. Backend stores the URL in the database (new column needed)
3. "Get Client Configuration" modal uses the registered satellite's URL
4. Self-hosted users see their correct satellite URL in the generated configuration

Suggested Implementation

1. Database Migration:

ALTER TABLE satellites ADD COLUMN public_url text;
ALTER TABLE satellites ADD COLUMN mcp_endpoint_url text;

2. Satellite Registration/Heartbeat:
Include DEPLOYSTACK_SATELLITE_URL in the registration payload and heartbeat data.

3. Backend API:
Store and return the satellite's public URL.

4. Frontend:
Fetch the satellite's URL from the API and use it in the client configuration modal.

Current Workaround

Self-hosted users must manually create their MCP client configuration, ignoring the UI-generated config:

{
  "mcpServers": {
    "deploystack": {
      "url": "https://your-satellite-domain.com/mcp",
      "type": "http"
    }
  }
}

Impact

This significantly impacts the self-hosted user experience:

• Confusing UX: Users see incorrect configuration that won't work with their setup
• Manual configuration required: Defeats the purpose of the "Get Client Configuration" feature
• Documentation gap: Self-hosted users have no guidance on constructing the correct URL
• Onboarding friction: New self-hosted users may not realize the displayed config is wrong

Additional Context

The documentation mentions DEPLOYSTACK_SATELLITE_URL:

When to set DEPLOYSTACK_SATELLITE_URL:

• Required when MCP clients (Claude Code, VS Code, etc.) connect via a domain or IP address
• Required for OAuth authentication to work with remote MCP clients

However, while the satellite accepts this environment variable, the value is never utilized in the client-facing configuration generation.

Related

This may also affect:

• OAuth callback URLs for MCP client authentication
• Any other features that need to know the satellite's public URL

Screenshots

Global Settings (correctly configured):

![Global Settings showing correct Backend URL and Frontend URL configuration]

Client Configuration Modal (showing incorrect hardcoded URL):

The modal displays satellite.deploystack.io instead of the configured self-hosted URL.

[Lasim]

done: