MCP Configuration Architecture

DeployStack implements a sophisticated three-tier configuration architecture for managing MCP server command line arguments and environment variables. This system supports multi-user teams while maintaining clean separation between fixed template parameters, shared team settings, and individual user configurations.

Architecture Overview

The three-tier system separates MCP server configuration into distinct layers:

1. Template Level - Fixed arguments and schemas defined in the MCP catalog
2. Team Level - Shared team configurations and credentials
3. User Level - Personal configurations for individual team members

This architecture solves the fundamental challenge of supporting multiple users within the same team installation while allowing individual customization.

Lock/Unlock Control System

The system's core feature is sophisticated lock/unlock controls that determine configuration boundaries:

Global Administrator Controls:

• Categorization: Classify every config element as Template/Team/User configurable
• Lock States: Set default_team_locked and visible_to_users controls
• Security Boundaries: Define what can never be changed vs. team/user configurable

Team Administrator Controls:

• Lock/Unlock Elements: Control what users can modify within schema boundaries
• Credential Management: Manage team secrets with visibility controls

Runtime Access:

• Users see only unlocked elements they can configure
• Locked elements are inherited but not modifiable

Design Problem

The Multi-User Team Challenge

Traditional MCP configurations assume a single user per installation. DeployStack's team-based approach requires supporting scenarios like:

Team Setup:

• Team: "DevOps Team"
• Members: User A, User B
• Devices: Each user has laptop + desktop
• Total Configurations: 4 different configurations for the same MCP server

User Requirements:

• User A needs access to /Users/userA/Desktop
• User B needs access to /Users/userB/Desktop and /Users/userB/Projects
• Both users share the same team API credentials
• Each user may have different debug settings

Solution Architecture

The three-tier system addresses this by:

1. Template Level: Defines what arguments are fixed vs configurable
2. Team Level: Manages shared credentials and team-wide settings
3. User Level: Allows individual customization per user and device

Database Schema

Tier 1: MCP Catalog (mcpServers)

The catalog defines the configuration structure for each MCP server type:

-- Template Level (with lock controls)
template_args: text('template_args')         -- [{value, locked, description}]
template_env: text('template_env')           -- Fixed environment variables

-- Team Schema (with lock/visibility controls) 
team_args_schema: text('team_args_schema')   -- Schema with lock controls
team_env_schema: text('team_env_schema')     -- [{name, type, required, default_team_locked, visible_to_users}]

-- User Schema
user_args_schema: text('user_args_schema')   -- User-configurable argument schema
user_env_schema: text('user_env_schema')     -- User-configurable environment schema

Tier 2: Team Installation (mcpServerInstallations)

Team installations manage shared configurations:

installation_name: text('installation_name') -- Team-friendly name
team_args: text('team_args')                 -- Team-level arguments (JSON array)
team_env: text('team_env')                   -- Team environment variables (JSON object)

Tier 3: User Configuration (mcpUserConfigurations)

Individual user configurations support multiple devices:

installation_id: text('installation_id')     -- References team installation
user_id: text('user_id')                     -- User who owns this config
device_name: text('device_name')             -- "MacBook Pro", "Work PC", etc.

user_args: text('user_args')                 -- User arguments (JSON array)
user_env: text('user_env')                   -- User environment variables (JSON object)

Configuration Flow

Runtime Assembly

Configuration Schema Step

Global administrators categorize configuration elements through the Configuration Schema Step:

1. Extract Elements: Parse Claude Desktop config for all args and env vars
2. Categorize Each Element: Assign to Template/Team/User tiers
3. Set Lock Controls: Define default_team_locked and visible_to_users
4. Generate Schema: Create the three-tier schema structure

Runtime Assembly

At runtime, configurations are assembled by merging all three tiers with lock/unlock controls applied:

const assembleConfiguration = (server, teamInstallation, userConfig) => {
  const finalArgs = [
    ...server.template_args.map(arg => arg.value), // Fixed template args
    ...(teamInstallation.team_args || []),          // Team shared args
    ...(userConfig.user_args || [])                 // User personal args
  ];
  
  const finalEnv = {
    ...(server.template_env || {}),                 // Fixed template env
    ...(teamInstallation.team_env || {}),           // Team shared env
    ...(userConfig.user_env || {})                  // User personal env
  };
  
  return { args: finalArgs, env: finalEnv };
};

Service Layer

McpUserConfigurationService

The service layer provides complete CRUD operations for user configurations:

Key Methods:

• createUserConfiguration() - Create new user config with validation
• getUserConfiguration() - Retrieve user config with team access control
• updateUserConfiguration() - Update with schema validation
• deleteUserConfiguration() - Remove user config
• updateUserArgs() - Partial update for arguments only
• updateUserEnv() - Partial update for environment variables only

Security Features:

• Team-based access control
• User isolation (users can only access their own configs)
• Schema validation against server-defined schemas
• Input sanitization and type checking

API Endpoints

API Endpoints

Configuration management through REST API:

• Team installations: /api/teams/{teamId}/mcp/installations/
• User configurations: /api/teams/{teamId}/mcp/installations/{installationId}/user-configs/
• Schema validation: Built into all endpoints

Schema Example

Configuration schema with lock/unlock controls:

{
  "template_args": [
    {"value": "-y", "locked": true, "description": ""},
    {"value": "@modelcontextprotocol/server-memory", "locked": true, "description": ""}
  ],
  "team_env_schema": [
    {
      "name": "MEMORY_FILE_PATH",
      "type": "string", 
      "required": true,
      "default_team_locked": true,
      "visible_to_users": false
    }
  ],
  "user_env_schema": [
    {
      "name": "DEBUG_MODE",
      "type": "string",
      "required": false,
      "locked": false
    }
  ]
}

Related Documentation

For specific implementation details:

• Backend API - Complete API endpoint documentation
• Database Schema - Database structure and relationships
• Teams - Team management and structure
• MCP Configuration System - User-facing configuration guide
• MCP Installation - Installation and team setup

The three-tier configuration architecture provides a robust foundation for managing complex MCP server configurations in multi-user team environments while maintaining security, flexibility, and ease of use.