feat(satellite): enhance MCP activity tracking with instance token support

Author: Lasim

services/backend/src/db/schema-tables/mcp-activity.ts

@@ -16,7 +16,7 @@ export const mcpClientActivity = pgTable('mcpClientActivity', {
   satellite_id: text('satellite_id').notNull().references(() => satellites.id, { onDelete: 'cascade' }),
 
   // Authentication (extensible for future)
-  auth_type: text('auth_type', { enum: ['oauth', 'api_key'] }).notNull(),
+  auth_type: text('auth_type', { enum: ['oauth', 'api_key', 'instance_token'] }).notNull(),
   oauth_client_id: text('oauth_client_id'), // References dynamicOauthClients.client_id
   api_key_id: text('api_key_id'), // Future: references to API key table
   auth_identifier: text('auth_identifier').notNull(), // Computed: 'oauth:{client_id}' or 'apikey:{key_id}'

services/backend/src/events/satellite/mcp-client-activity.ts

@@ -19,10 +19,19 @@ export const SCHEMA = {
       minLength: 1,
       description: 'Team ID in which the requests were made'
     },
-    oauth_client_id: { 
-      type: 'string', 
+    oauth_client_id: {
+      type: 'string',
       minLength: 1,
-      description: 'OAuth client ID of the MCP client'
+      description: 'OAuth client ID or installation ID of the MCP client'
+    },
+    auth_type: {
+      type: 'string',
+      enum: ['oauth', 'instance_token'],
+      description: 'Authentication method used by the MCP client'
+    },
+    auth_identifier: {
+      type: 'string',
+      description: 'Pre-computed auth identifier (e.g. instance:{installation_id})'
     },
     client_name: { 
       type: 'string',
@@ -57,11 +66,10 @@ export const SCHEMA = {
     }
   },
   required: [
-    'user_id', 
-    'team_id', 
-    'oauth_client_id', 
-    'request_count', 
-    'tool_call_count', 
+    'user_id',
+    'team_id',
+    'request_count',
+    'tool_call_count',
     'last_activity_at'
   ],
   additionalProperties: true
@@ -70,7 +78,9 @@ export const SCHEMA = {
 interface McpClientActivityData {
   user_id: string;
   team_id: string;
-  oauth_client_id: string;
+  oauth_client_id?: string;
+  auth_type?: 'oauth' | 'instance_token';
+  auth_identifier?: string;
   client_name?: string;
   user_agent?: string;
   ip_address?: string;
@@ -96,6 +106,7 @@ async function updateCumulativeActivity(
   satelliteId: string,
   data: McpClientActivityData,
   authIdentifier: string,
+  authType: 'oauth' | 'api_key' | 'instance_token',
   activityTimestamp: Date,
   eventTimestamp: Date
 ): Promise<void> {
@@ -127,8 +138,8 @@ async function updateCumulativeActivity(
       user_id: data.user_id,
       team_id: data.team_id,
       satellite_id: satelliteId,
-      auth_type: 'oauth',
-      oauth_client_id: data.oauth_client_id,
+      auth_type: authType,
+      oauth_client_id: data.oauth_client_id || null,
       api_key_id: null,
       auth_identifier: authIdentifier,
       client_name: data.client_name || null,
@@ -197,14 +208,16 @@ export async function handle(
   logger: FastifyBaseLogger
 ): Promise<void> {
   const data = eventData as unknown as McpClientActivityData;
-  const authIdentifier = `oauth:${data.oauth_client_id}`;
+  const authType = data.auth_type || 'oauth';
+  const authIdentifier = data.auth_identifier || `oauth:${data.oauth_client_id}`;
   const activityTimestamp = new Date(data.last_activity_at);
 
   await updateCumulativeActivity(
     db,
     satelliteId,
     data,
     authIdentifier,
+    authType,
     activityTimestamp,
     eventTimestamp
   );

services/satellite/src/core/instance-router.ts

@@ -11,6 +11,8 @@ import { McpToolExecutor } from '../lib/mcp-tool-executor';
 import { McpSessionManager } from '../lib/mcp-session-manager';
 import { UnifiedToolDiscoveryManager } from '../services/unified-tool-discovery-manager';
 import { DynamicConfigManager } from '../services/dynamic-config-manager';
+import { McpActivityTracker } from '../services/mcp-activity-tracker';
+import { trackMcpActivity } from '../services/activity-tracking-helper';
 import { ProcessManager } from '../process';
 import { McpServerConfig } from '../services/command-polling-service';
 
@@ -40,6 +42,7 @@ export class InstanceRouter {
   private configManager: DynamicConfigManager;
   private toolDiscoveryManager: UnifiedToolDiscoveryManager;
   private processManager: ProcessManager;
+  private activityTracker?: McpActivityTracker;
 
   constructor(deps: {
     logger: FastifyBaseLogger;
@@ -48,13 +51,15 @@ export class InstanceRouter {
     configManager: DynamicConfigManager;
     toolDiscoveryManager: UnifiedToolDiscoveryManager;
     processManager: ProcessManager;
+    activityTracker?: McpActivityTracker;
   }) {
     this.logger = deps.logger.child({ component: 'InstanceRouter' });
     this.toolExecutor = deps.toolExecutor;
     this.sessionManager = deps.sessionManager;
     this.configManager = deps.configManager;
     this.toolDiscoveryManager = deps.toolDiscoveryManager;
     this.processManager = deps.processManager;
+    this.activityTracker = deps.activityTracker;
   }
 
   /**
@@ -88,6 +93,10 @@ export class InstanceRouter {
     // Register tools/call handler - execute on THIS instance
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const { name: toolName, arguments: toolArgs } = request.params;
+      const startTime = Date.now();
+      let result: any;
+      let success = true;
+      let errorMessage: string | undefined;
 
       // Look up the tool in the discovery cache to get its correct namespacedName.
       // processId is the installation name (e.g., "duckduckgo-mcp-server-john-plhdo1j4kuit0et-..."),
@@ -117,13 +126,40 @@ export class InstanceRouter {
         namespaced_name: matchedTool.namespacedName
       }, `Executing tool ${toolName} on instance ${processId}`);
 
-      const result = await this.toolExecutor.executeToolCall(
-        matchedTool.namespacedName, // e.g., "duckduckgo-mcp-server:search"
-        toolArgs || {},
-        processId // Force routing to this specific process
-      );
+      try {
+        result = await this.toolExecutor.executeToolCall(
+          matchedTool.namespacedName, // e.g., "duckduckgo-mcp-server:search"
+          toolArgs || {},
+          processId // Force routing to this specific process
+        );
 
-      return result;
+        return result;
+      } catch (error) {
+        success = false;
+        errorMessage = error instanceof Error ? error.message : String(error);
+        throw error;
+      } finally {
+        const responseTimeMs = Date.now() - startTime;
+
+        // Buffer request log (mirrors mcp-server-wrapper.ts finally block)
+        const serverConfig = this.configManager.getMcpServerConfig(processId);
+        const loggingEnabled = serverConfig?.settings?.request_logging_enabled !== false;
+
+        if (serverConfig?.installation_id && serverConfig?.team_id && loggingEnabled) {
+          this.toolExecutor.bufferRequestLogEntry({
+            installation_id: serverConfig.installation_id,
+            team_id: serverConfig.team_id,
+            user_id: serverConfig.user_id,
+            tool_name: toolName,
+            tool_params: toolArgs || {},
+            tool_response: result,
+            response_time_ms: responseTimeMs,
+            success,
+            error_message: errorMessage,
+            timestamp: new Date().toISOString()
+          });
+        }
+      }
     });
 
     this.logger.info({
@@ -259,6 +295,16 @@ export class InstanceRouter {
         instance_path: instancePath,
         process_id: instanceConfig.processId
       }, 'Instance authentication successful');
+
+      // Track activity for personal dashboard (same pipeline as OAuth auth)
+      if (this.activityTracker && instanceConfig.config.user_id && instanceConfig.config.team_id) {
+        trackMcpActivity(this.activityTracker, request, {
+          userId: instanceConfig.config.user_id,
+          teamId: instanceConfig.config.team_id,
+          authIdentifier: instanceConfig.config.installation_id || instanceConfig.processId,
+          authType: 'instance_token',
+        }, this.logger);
+      }
     };
 
     // POST /i/:instancePath/mcp - Client-to-server MCP messages

services/satellite/src/events/registry.ts

@@ -57,6 +57,8 @@ export interface EventDataMap {
     user_id: string;
     team_id: string;
     oauth_client_id: string;
+    auth_type?: 'oauth' | 'instance_token';
+    auth_identifier?: string;
     client_name: string;
     user_agent: string;
     ip_address: string;

services/satellite/src/jobs/mcp-activity-report-job.ts

@@ -63,6 +63,10 @@ export class McpActivityReportJob extends BaseJob {
           user_id: activity.userId,
           team_id: activity.teamId,
           oauth_client_id: activity.oauthClientId,
+          auth_type: activity.authType,
+          auth_identifier: activity.authType === 'instance_token'
+            ? `instance:${activity.oauthClientId}`
+            : undefined,
           client_name: activity.clientName,
           user_agent: activity.userAgent,
           ip_address: activity.ipAddress,

services/satellite/src/middleware/auth-middleware.ts

@@ -1,7 +1,7 @@
 import type { FastifyRequest, FastifyReply } from 'fastify';
 import { TokenIntrospectionService, TokenValidationResult } from '../services/token-introspection-service';
 import { McpActivityTracker } from '../services/mcp-activity-tracker';
-import { deriveClientName, extractSessionId, extractIpAddress } from '../services/client-name-detector';
+import { trackMcpActivity } from '../services/activity-tracking-helper';
 
 // Extend FastifyRequest to include authentication context
 declare module 'fastify' {
@@ -85,51 +85,12 @@ export function requireAuthentication(
 
       // Track MCP client activity for personal dashboard (if tracker provided)
       if (activityTracker && request.auth.client_id) {
-        try {
-          const clientName = deriveClientName(request.headers as Record<string, string | string[] | undefined>);
-          const sessionId = extractSessionId(request.headers as Record<string, string | string[] | undefined>);
-          const ipAddress = extractIpAddress(
-            request.headers as Record<string, string | string[] | undefined>,
-            request.socket.remoteAddress
-          );
-          const userAgent = request.headers['user-agent'] || 'unknown';
-          
-          // Check if this is a tool call (mcp.tool.executed)
-          // This is a simple heuristic - more sophisticated detection can be added later
-          let isToolCall = false;
-          if (request.url.includes('tools/call')) {
-            isToolCall = true;
-          } else if (request.body && typeof request.body === 'object' && 'method' in request.body) {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            isToolCall = (request.body as any).method === 'tools/call';
-          }
-
-          activityTracker.trackRequest(
-            request.auth.user.id,
-            request.auth.team.id,
-            request.auth.client_id,
-            clientName,
-            userAgent,
-            ipAddress,
-            sessionId,
-            isToolCall
-          );
-
-          request.log.debug({
-            operation: 'activity_tracked',
-            userId: request.auth.user.id,
-            teamId: request.auth.team.id,
-            clientId: request.auth.client_id,
-            clientName,
-            isToolCall
-          }, 'MCP client activity tracked');
-        } catch (error) {
-          // Activity tracking failure is non-fatal
-          request.log.warn({
-            operation: 'activity_tracking_failed',
-            error: error instanceof Error ? error.message : String(error)
-          }, 'Failed to track MCP client activity (non-fatal)');
-        }
+        trackMcpActivity(activityTracker, request, {
+          userId: request.auth.user.id,
+          teamId: request.auth.team.id,
+          authIdentifier: request.auth.client_id,
+          authType: 'oauth',
+        }, request.log);
       }
 
     } catch (error) {

services/satellite/src/server.ts

@@ -1267,7 +1267,8 @@ export async function createServer() {
     sessionManager: instanceSessionManager, // Separate session manager
     configManager: dynamicConfigManager,
     toolDiscoveryManager,
-    processManager
+    processManager,
+    activityTracker,
   });
 
   // Setup instance router routes

services/satellite/src/services/activity-tracking-helper.ts

@@ -0,0 +1,68 @@
+import type { FastifyRequest, FastifyBaseLogger } from 'fastify';
+import { McpActivityTracker } from './mcp-activity-tracker';
+import { deriveClientName, extractSessionId, extractIpAddress } from './client-name-detector';
+
+export interface ActivityTrackingContext {
+  userId: string;
+  teamId: string;
+  authIdentifier: string;
+  authType: 'oauth' | 'instance_token';
+}
+
+/**
+ * Shared activity tracking logic for MCP requests.
+ *
+ * Called from both the OAuth auth middleware (hierarchical router)
+ * and the instance router (path-based access) to avoid duplication.
+ * Tracking failure is non-fatal — errors are logged but never propagated.
+ */
+export function trackMcpActivity(
+  activityTracker: McpActivityTracker,
+  request: FastifyRequest,
+  context: ActivityTrackingContext,
+  logger: FastifyBaseLogger
+): void {
+  try {
+    const headers = request.headers as Record<string, string | string[] | undefined>;
+    const clientName = deriveClientName(headers);
+    const sessionId = extractSessionId(headers);
+    const ipAddress = extractIpAddress(headers, request.socket.remoteAddress);
+    const userAgent = request.headers['user-agent'] || 'unknown';
+
+    // Detect tool call from URL path or JSON-RPC body
+    let isToolCall = false;
+    if (request.url.includes('tools/call')) {
+      isToolCall = true;
+    } else if (request.body && typeof request.body === 'object' && 'method' in request.body) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      isToolCall = (request.body as any).method === 'tools/call';
+    }
+
+    activityTracker.trackRequest(
+      context.userId,
+      context.teamId,
+      context.authIdentifier,
+      clientName,
+      userAgent,
+      ipAddress,
+      sessionId,
+      isToolCall,
+      context.authType
+    );
+
+    logger.debug({
+      operation: 'activity_tracked',
+      userId: context.userId,
+      teamId: context.teamId,
+      authIdentifier: context.authIdentifier,
+      authType: context.authType,
+      clientName,
+      isToolCall
+    }, 'MCP client activity tracked');
+  } catch (error) {
+    logger.warn({
+      operation: 'activity_tracking_failed',
+      error: error instanceof Error ? error.message : String(error)
+    }, 'Failed to track MCP client activity (non-fatal)');
+  }
+}