Enhance documentation for database connection patterns and MCP endpoint integration, emphasizing best practices for dynamic database access and security improvements in device registration processes.

Author: Lasim

docs/development/backend/database.mdx

@@ -147,6 +147,29 @@ import { drizzle } from 'drizzle-orm/better-sqlite3';
 import { drizzle } from 'drizzle-orm/libsql';
 ```
 
+### Database Connection Patterns
+
+When accessing the database in route handlers, always use `getDb()` to obtain the database connection dynamically:
+
+```typescript
+import { getDb } from '../../../db';
+import { YourService } from '../../../services/yourService';
+
+export default async function yourRoute(server: FastifyInstance) {
+  const db = getDb();
+  const yourService = new YourService(db);
+  // ... rest of route handler
+}
+```
+
+**Why this pattern is required:**
+- `server.db` may be `null` during certain initialization states
+- `getDb()` always returns the active database connection
+- This ensures consistent behavior across all endpoints
+- Other working endpoints already follow this pattern
+
+**Avoid:** Direct usage of `server.db` as it can cause "Cannot read properties of null" errors.
+
 ## Database Structure
 
 The database schema is defined in `src/db/schema.sqlite.ts`. This is the **single source of truth** for all database schema definitions and works across all supported database types.

docs/development/gateway/mcp.mdx

@@ -20,12 +20,20 @@ The Gateway implements a sophisticated MCP configuration system that:
 
 ## API Integration
 
-### Endpoint
-The Gateway fetches MCP installations from:
+### Legacy Team-Based Endpoint
+The Gateway can fetch MCP installations from the legacy team-based endpoint:
 ```
 GET /api/teams/{teamId}/mcp/installations
 ```
 
+### Modern Three-Tier Gateway Endpoint
+For optimal performance and device-specific configurations, the Gateway uses the modern three-tier endpoint:
+```
+GET /api/gateway/me/mcp-configurations?hardware_id={hardwareId}
+```
+
+This endpoint automatically merges Template + Team + User configurations and returns ready-to-use server configurations with device-specific user arguments and environment variables. For detailed information about this endpoint, see the [Backend API Documentation](/development/backend/api).
+
 ### Response Structure
 The API returns team MCP installations with this interface:
 ```typescript

docs/development/gateway/oauth.mdx

@@ -87,9 +87,10 @@ During the token exchange process, the gateway automatically registers the curre
 
 **Security Benefits:**
 - Device registration happens only during authenticated login sessions
-- No separate device registration endpoints (enhanced security)
+- **No separate device registration endpoints exist** - this prevents unauthorized device registration and enhances security
 - Hardware fingerprinting provides unique device identification
 - Enables device management and access control in the backend
+- Eliminates the need for manual device registration API calls
 
 **Process Flow:**
 1. Gateway detects current device information using system APIs
@@ -289,9 +290,12 @@ When device registration succeeds, the backend includes device information in th
 
 **Security Design:**
 - Device registration only occurs during authenticated OAuth2 flows
-- No separate device creation endpoints exist (prevents unauthorized device registration)
-- Hardware fingerprinting ensures unique device identification
+- **No separate device creation endpoints exist** - this architectural decision prevents unauthorized device registration and eliminates potential security vulnerabilities
+- Hardware fingerprinting ensures unique device identification across multiple login sessions
 - Device information is validated using JSON schema before processing
+- Gateway automatically handles device lookup using hardware fingerprints without requiring manual registration
+
+For comprehensive information about device management and hardware fingerprinting, see the [Device Management Documentation](/device-management).
 
 ## Security Considerations