> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deploystack.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Team Isolation Implementation

> Technical implementation of OAuth-based team and user separation in DeployStack Satellite for per-user MCP server instance access control.

DeployStack Satellite implements OAuth 2.1 Resource Server-based team and user isolation to provide secure multi-tenant access to per-user MCP server instances. This system ensures complete separation of team resources AND per-user instances while maintaining a unified MCP client interface.

For OAuth authentication details, see [OAuth Authentication Implementation](/development/satellite/oauth-authentication). For tool discovery mechanics, see [Tool Discovery Implementation](/development/satellite/tool-discovery). For per-user instance lifecycle, see [Instance Lifecycle Management](/development/satellite/instance-lifecycle).

## Technical Architecture

### Team and User Context Resolution

Isolation operates through OAuth token introspection that extracts both team AND user context from validated Bearer tokens:

```
MCP Client Request → OAuth Token → Token Introspection → Team + User Context → Resource Filtering
     │                   │              │                        │                    │
  Bearer Token      Satellite API    Backend Validation   Team ID + User ID    User's Instances
  (user-scoped)     Key Required     5-minute Cache           Extraction         Database Query
```

**Core Components:**

* **TokenIntrospectionService**: Validates tokens via Backend introspection endpoint
* **TeamAwareMcpHandler**: Filters MCP resources based on team AND user permissions
* **DynamicConfigManager**: Provides per-user instance mappings from Backend polling
* **RemoteToolDiscoveryManager**: Caches tools with per-user server association metadata

### Per-User Instance Mapping Architecture

Isolation relies on database-backed per-user instance mappings:

```
Team "acme" + User "alice" → Instance "context7-acme-alice-R36no6FGoMFEZO9nWJJLT"
Team "acme" + User "bob"   → Instance "context7-acme-bob-R36no6FGoMFEZO9nWJJLT"
Team "beta" + User "charlie" → Instance "context7-beta-charlie-S47mp8GHpNGFZP0oWKKMU"
```

**Database Integration:**

* **mcpServerInstances Table**: Links users to their specific MCP server instances (per user)
* **mcpServerInstallations Table**: Links teams to MCP server installations (team-level)
* **Dynamic Configuration**: Backend polling delivers per-user instance mappings
* **Instance Naming**: Format `{server_slug}-{team_slug}-{user_slug}-{installation_id}`
* **Complete Isolation**: Users only access their OWN instances, not teammates' instances

<Info>
  **Per-User Instances:** Each team member has their own independent instance for each MCP server. This enables user-specific configuration (Template + Team + User merged config) and independent status tracking per user.
</Info>

## Tool Discovery Integration

### Friendly Tool Naming

Tool discovery uses `server_slug` for user-friendly tool names while maintaining internal per-user instance routing:

**User-Facing Names:**

* `context7-resolve-library-id`
* `context7-get-library-docs`

**Internal Per-User Instance Resolution:**

* Team "acme" + User "alice": Routes to `context7-acme-alice-R36no6FGoMFEZO9nWJJLT`
* Team "acme" + User "bob": Routes to `context7-acme-bob-R36no6FGoMFEZO9nWJJLT`
* Team "beta" + User "charlie": Routes to `context7-beta-charlie-S47mp8GHpNGFZP0oWKKMU`

**Implementation Details:**

* **RemoteToolDiscoveryManager**: Creates friendly names using `config.server_slug`
* **CachedTool Interface**: Stores both `namespacedName` and `serverName` for routing
* **TeamAwareMcpHandler**: Resolves team AND user context to actual per-user instances

### Tool Filtering Process

Per-user tool filtering operates at the MCP protocol level:

```
tools/list Request → OAuth User Context → Filter by User's Instances → Return Filtered Tools
     │                      │                       │                         │
  Bearer Token     Team + User ID Extraction   Database Lookup         User-Specific List
  Validation          from Token Cache         User's Instances        JSON-RPC Response
```

**Filtering Logic:**

1. **Token Validation**: Extract team ID AND user ID from OAuth token introspection
2. **Instance Resolution**: Query user's allowed MCP server instances (only THEIR instances)
3. **Tool Filtering**: Include only tools from user's OWN instances that are `online`
4. **Response Generation**: Return filtered tool list to MCP client

<Info>
  **User-Specific Filtering:** Each user sees only tools from their OWN instances. Other team members' instance status does NOT affect your tool availability. If your instance is `awaiting_user_config`, you see NO tools from that server until you complete configuration.
</Info>

## OAuth Integration Points

### Authentication Middleware Integration

Team isolation integrates with existing OAuth authentication middleware:

**File References:**

* `services/satellite/src/middleware/auth-middleware.ts` - Bearer token validation
* `services/satellite/src/services/token-introspection-service.ts` - Token validation with caching
* `services/satellite/src/services/team-aware-mcp-handler.ts` - Team-filtered MCP operations

**Authentication Flow:**

1. **Bearer Token Extraction**: From Authorization header
2. **Token Introspection**: Backend validation with 5-minute caching
3. **Team Context Storage**: In `request.auth.team` object
4. **MCP Request Processing**: Team-aware filtering applied

### Token Introspection Response

Backend token introspection provides team AND user context:

```
Introspection Response:
{
  "active": true,
  "sub": "user_uuid",
  "user_id": "user_uuid",
  "team_id": "team_uuid",
  "team_name": "acme",
  "team_role": "admin",
  "scope": "mcp:read mcp:tools:execute"
}
```

**Context Fields:**

* **sub**: User identifier (OAuth standard field)
* **user\_id**: Database UUID for user identification
* **team\_id**: Database UUID for team identification
* **team\_name**: Human-readable team identifier (slug)
* **team\_role**: User's role within the team
* **scope**: OAuth scopes for permission validation

<Info>
  **User Context Required:** The `user_id` field is critical for per-user instance resolution. It enables the satellite to route tool calls to the correct user's process, ensuring complete isolation between team members.
</Info>

## Server Instance Resolution

### Dynamic Server Mapping

Team-server mappings are delivered via Backend polling system:

**Configuration Source:**

* **Backend Database**: `mcpServerInstallations` table
* **Polling Mechanism**: Existing satellite configuration sync
* **Update Frequency**: Based on Backend polling intervals
* **Cache Storage**: In-memory via DynamicConfigManager

### Server Resolution Algorithm

Tool execution resolves team AND user context to specific per-user instances:

```
Tool Call "context7-resolve-library-id" + Team "acme" + User "alice"
    ↓
Find Instance: server_slug="context7" AND team_id="acme_uuid" AND user_id="alice_uuid"
    ↓
Resolve to: "context7-acme-alice-R36no6FGoMFEZO9nWJJLT"
    ↓
Route Request: HTTP proxy OR stdio process to user's specific instance
```

**Resolution Process:**

1. **Parse Tool Name**: Extract `server_slug` from namespaced tool name
2. **Team + User Context**: Get team ID AND user ID from OAuth token validation
3. **Instance Lookup**: Find user's instance: `server_slug` + `team_id` + `user_id`
4. **Route Execution**: Execute tool on user's specific instance (not teammates' instances)

## Security Implementation

### Complete Team Isolation

Team isolation provides enterprise-grade security:

**Access Control:**

* **Token-Based**: All requests require valid OAuth Bearer tokens
* **Team Scoping**: Tokens are issued for specific team contexts
* **Server Isolation**: Teams cannot access other teams' MCP server instances
* **Tool Filtering**: Only team's tools visible in discovery

**Security Boundaries:**

* **Network Level**: HTTP proxy routes to team-specific server instances
* **Application Level**: TeamAwareMcpHandler enforces team permissions
* **Data Level**: Complete separation of team resources and configurations

### Audit and Logging

Team isolation includes comprehensive audit logging:

**Log Categories:**

* **Authentication Events**: Token validation and team context extraction
* **Access Control**: Team permission checks and access denials
* **Tool Execution**: Team-scoped tool calls with server resolution
* **Configuration Changes**: Team-server mapping updates

**Log Format:**

```
operation: "team_tool_access_granted"
team_id: "team_uuid"
server_name: "context7-john-R36no6FGoMFEZO9nWJJLT"
namespaced_tool_name: "context7-resolve-library-id"
```

## Development Integration

### Service Initialization

Team isolation services initialize after satellite registration:

**Initialization Order:**

1. **Satellite Registration**: Obtain API key from Backend
2. **OAuth Services**: Initialize TokenIntrospectionService
3. **Team Handler**: Create TeamAwareMcpHandler instance
4. **Route Integration**: Apply authentication middleware to MCP endpoints

**File References:**

* `services/satellite/src/server.ts` - Service initialization
* `services/satellite/src/routes/mcp.ts` - MCP endpoint authentication
* `services/satellite/src/routes/sse.ts` - SSE endpoint authentication

### Error Handling

Team isolation implements comprehensive error handling:

**Authentication Errors:**

* **Invalid Token**: 401 with OAuth 2.1 compliant error response
* **Insufficient Scope**: 403 with required scope information
* **Team Access Denied**: 403 with available server list

**Resolution Errors:**

* **Server Not Found**: Tool execution fails with descriptive error
* **Team Mapping Missing**: Configuration error with Backend sync status
* **Tool Not Available**: Clear error with available tool list

## Performance Characteristics

### Token Validation Caching

Token introspection includes 5-minute caching for performance:

**Cache Implementation:**

* **Memory Storage**: Hashed token keys for security
* **TTL Management**: 5-minute expiration with automatic cleanup
* **Cache Hit Rate**: Reduces Backend introspection calls
* **Security**: No actual token values stored in cache

### Team Filtering Performance

Tool filtering operates with minimal overhead:

**Performance Metrics:**

* **Tool Filtering**: O(n) where n = total cached tools
* **Server Resolution**: O(1) hash map lookup
* **Memory Usage**: Shared tool cache across all teams
* **Network Overhead**: Single Backend introspection per token

### Scalability Considerations

Team isolation scales efficiently for multi-tenant deployment:

**Scaling Factors:**

* **Team Limit**: No hard limit, memory-bound by server instances
* **Tool Cache**: Shared across teams for memory efficiency
* **Token Cache**: Bounded by active user sessions
* **Backend Integration**: Leverages existing polling infrastructure

## Integration with Existing Systems

### Backend Communication

Team isolation integrates with existing Backend systems:

**API Integration:**

* **Token Introspection**: Uses existing OAuth 2.1 introspection endpoint
* **Configuration Polling**: Leverages existing satellite polling system
* **Database Schema**: Extends existing `mcpServerInstallations` table
* **Authentication**: Uses satellite API key for Backend communication

### MCP Client Compatibility

Team isolation maintains full MCP client compatibility:

**Client Requirements:**

* **OAuth Support**: MCP clients must support OAuth 2.1 authentication
* **Bearer Tokens**: Standard Authorization header implementation
* **No Team Awareness**: Clients remain unaware of team concepts
* **Standard MCP**: Full compliance with MCP protocol specification

<Info>
  **Implementation Status**: Team isolation is fully implemented and operational. The system provides complete team separation while maintaining MCP client compatibility and leveraging existing OAuth 2.1 authentication infrastructure.
</Info>

## Related Documentation

* [OAuth Authentication Implementation](/development/satellite/oauth-authentication) - OAuth 2.1 Resource Server details
* [Tool Discovery Implementation](/development/satellite/tool-discovery) - Tool caching and namespacing mechanics
* [Satellite Architecture Design](/development/satellite/architecture) - Overall satellite architecture
* [Backend Communication](/development/satellite/backend-communication) - Backend integration patterns
* [Backend OAuth2 Server Implementation](/development/backend/oauth2-server) - OAuth server implementation