Delete Server

Permanently remove an MCP server from the SuperBox registry

DELETE /servers/:name

Delete Server

cURL

curl --request DELETE \
  --url https://api.example.com/servers/:name

200 Success

{
  "success": true,
  "data": {
    "name": "my-test-server",
    "deleted_at": "2025-12-09T10:30:00Z",
    "activeUsers": 5,
    "backupId": "backup_abc123def456",
    "message": "Server deleted successfully. Backup available for 30 days for recovery."
  },
  "meta": {
    "timestamp": "2025-12-09T10:30:00Z",
    "version": "v1",
    "requestId": "req_xyz789"
  }
}

Endpoint

DELETE https://api.superbox.ai/api/v1/servers/:name

Authentication

Required

This endpoint requires authentication. You must be the server owner.

Only the server owner can delete a server. This action is irreversible.

Path Parameters

name · string · required

Unique server identifier to delete Example: weather-mcp, my-test-server

Query Parameters

confirm · boolean · default: "false"

Confirmation flag to prevent accidental deletions Must be: true to proceed with deletion

force · boolean · default: "false"

Force deletion even if server has active users

Use with caution. This may disrupt users actively using your server.

Response

success · boolean

Indicates if deletion was successful

data · object

Deletion confirmation details

Show properties

name · string

Name of deleted server

deleted_at · string

ISO 8601 timestamp of deletion

activeUsers · integer

Number of active users at time of deletion

backupId · string

Backup identifier for recovery (valid for 30 days)

message · string

Deletion confirmation message

Examples

cURL
# Basic deletion (requires confirm=true)
curl -X DELETE "https://api.superbox.ai/api/v1/servers/my-test-server?confirm=true" \
  -H "Authorization: Bearer $SUPERBOX_API_TOKEN"

# Force deletion with active users

curl -X DELETE "https://api.superbox.ai/api/v1/servers/my-server?confirm=true&force=true" \
 -H "Authorization: Bearer $SUPERBOX_API_TOKEN"

Response Examples

200 Success

{
  "success": true,
  "data": {
    "name": "my-test-server",
    "deleted_at": "2025-12-09T10:30:00Z",
    "activeUsers": 5,
    "backupId": "backup_abc123def456",
    "message": "Server deleted successfully. Backup available for 30 days for recovery."
  },
  "meta": {
    "timestamp": "2025-12-09T10:30:00Z",
    "version": "v1",
    "requestId": "req_xyz789"
  }
}

Deletion Process

When you delete a server, SuperBox performs these steps:

1. Validation

   • Verify authentication and ownership - Check for confirmation flag - Check for active users (unless force=true)
2. Backup Creation

   • Create backup of server metadata - Store backup for 30-day recovery period - Generate unique backup ID
3. Lambda Cleanup

   • Stop Lambda function - Delete function configuration - Remove ECR container images
4. Registry Update

   • Remove from S3 registry - Update search indexes - Clear cached data
5. User Notification

   • Notify active users (if any) - Send confirmation email to owner - Update analytics

What Gets Deleted

Immediately Deleted

• Server listing in registry - Lambda function and containers - Public API access - Search index entries - CDN cached data

Retained (30 days)

• Server metadata backup - Security scan reports - Analytics data - Usage statistics

Recovery is possible within 30 days by contacting support with backup ID

Permanently Retained

• Transaction history (for compliance) - Audit logs - User reviews (anonymized)
  Required for financial and legal compliance

Before You Delete

Check Active Users

async function checkActiveUsers(serverName) {
  const response = await fetch(
    `https://api.superbox.ai/api/v1/servers/${serverName}/stats`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.SUPERBOX_API_TOKEN}`
      }
    }
  );
  
  const stats = await response.json();
  console.log(`Active users: ${stats.data.activeUsers}`);
  console.log(`Daily executions: ${stats.data.dailyExecutions}`);
  
  if (stats.data.activeUsers > 0) {
    console.warn('⚠ Server has active users!');
  }
}

Export Data

def export_server_data(server_name):
    """Export all server data before deletion"""
    
    # Get server details
    url = f"https://api.superbox.ai/api/v1/servers/{server_name}"
    headers = {'Authorization': f'Bearer {os.getenv("SUPERBOX_API_TOKEN")}'}
    
    response = requests.get(url, headers=headers)
    server_data = response.json()['data']
    
    # Save to file
    import json
    with open(f'{server_name}_backup.json', 'w') as f:
        json.dump(server_data, f, indent=2)
    
    print(f"✓ Data exported to {server_name}_backup.json")
    
    # Get analytics
    analytics_url = f"{url}/analytics"
    analytics = requests.get(analytics_url, headers=headers).json()
    
    with open(f'{server_name}_analytics.json', 'w') as f:
        json.dump(analytics['data'], f, indent=2)
    
    print(f"✓ Analytics exported to {server_name}_analytics.json")

Notify Users

Consider notifying your users before deletion:

• Post announcement on your homepage
• Email active users (if you have their contacts)
• Update README with deprecation notice
• Suggest alternative servers

// Update description before deletion
await fetch(url, {
  method: 'PUT',
  headers,
  body: JSON.stringify({
    description: 'DEPRECATED - This server will be deleted on 2025-12-20. Please migrate to alternative-server.'
  })
});

Consider Deprecation Instead

Instead of deleting, you can deprecate:

// Mark as deprecated
await fetch(url, {
  method: 'PUT',
  headers,
  body: JSON.stringify({
    metadata: {
      deprecated: true,
      deprecation_date: '2025-12-09',
      alternative: 'new-improved-server'
    }
  })
});

Deprecation allows users to migrate gradually

Common Deletion Scenarios

Test Server

Scenario: Deleting a test/development server

# Quick deletion (no active users expected)
curl -X DELETE \
  "https://api.superbox.ai/api/v1/servers/test-server?confirm=true" \
  -H "Authorization: Bearer $TOKEN"

Safe to delete immediately

Migrating

Scenario: Moving to a new server name

// 1. Create new server
await createServer(newServerData);

// 2. Update old server description
await updateServer(oldName, {
  description: `MOVED to ${newName} - Please update your configuration`
});

// 3. Wait 30 days for migration
// 4. Delete old server
await deleteServer(oldName);

Security Issue

Scenario: Critical security vulnerability

// Force immediate deletion
await fetch(
  `${url}?confirm=true&force=true`,
  { method: 'DELETE', headers }
);

Use force deletion for security emergencies

Paid Server

Scenario: Deleting a paid server

Considerations:

• Refund active subscribers
• Export transaction history
• Update payment provider
• Notify customers

# Check revenue before deletion
stats = get_server_stats('paid-server')
print(f"Total revenue: ${stats['totalRevenue']}")
print(f"Active subscriptions: {stats['activeSubscriptions']}")

Recovery Process

If you deleted by mistake, you can recover within 30 days:

1. Contact Support

   Email [e-mail] with: - Server name - Backup ID (from deletion response) - Reason for recovery

2. Verification

   Support will verify: - Your ownership - Backup existence - Recovery eligibility

3. Restoration

   If approved: - Server metadata restored - Lambda function redeployed - Registry updated - Takes 15-30 minutes

4. Confirmation

   You’ll receive: - Restoration confirmation email - Updated server URL - Post-recovery checklist

Recovery is only available for 30 days after deletion

Best Practices

Export First

Always export server data and analytics before deletion

Notify Users

Give users advance notice (7-30 days recommended)

Save Backup ID

Store the backup ID in case you need to recover

Check Dependencies

Ensure no other systems depend on your server

Consider Alternatives

Deprecation or making private instead of deletion

Double Confirmation

Use UI confirmation dialogs to prevent accidents

Alternative Actions

Instead of deletion, consider:

Make Private

// Make server private (coming soon)
await updateServer(name, {
  visibility: 'private'
});

Transfer Ownership

// Transfer to another user (coming soon)
await transferServer(name, {
  newOwner: '[e-mail]'
});

Archive

// Mark as archived
await updateServer(name, {
  metadata: {
    archived: true,
    archived_date: new Date().toISOString()
  }
});

Security Considerations

Important Security Notes: - Deletion does not remove git history - Public forks of your repository remain accessible - User-generated content (reviews) is anonymized but retained - Transaction data is retained for compliance If your server contained sensitive information: 1. Delete from source repository 2. Rotate any exposed credentials 3. Contact support for additional cleanup

Related Endpoints

Get Server

View server details before deletion

Update Server

Update instead of deleting

Create Server

Create a replacement server

Think carefully before deleting. Deprecation is often a better choice!