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.

Server Sources

MCP servers in the catalog come from two sources, both using the same three-tier configuration architecture:

Official Registry Servers (Automatic)

Source: Synced automatically from registry.modelcontextprotocol.io
Schema Creation: Automatic transformation via RegistrySyncService and background jobs
Configuration Mapping: Environment variables from registry automatically categorized into three tiers
Transport Detection: Automatically derived from packages (stdio) or remotes (HTTP/SSE)
Maintenance: Updates sync automatically from official registry

Manual Servers (Custom)

Source: Created manually by global administrators
Schema Creation: Manual categorization through Configuration Schema Step
Configuration Mapping: Precise admin control over every element
Transport: Explicitly configured by administrator
Maintenance: Manual updates as needed

Key Point: Both server types use the identical three-tier configuration system at runtime. The difference is in how schemas are initially created.

Architecture Overview

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

Template Level - Fixed arguments and schemas defined in the MCP catalog
Team Level - Shared team configurations and credentials
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
Total Configurations: 2 different user configurations for the same MCP server

User Requirements:

User A needs personal search preferences (Google, 10 results per page)
User B needs different preferences (Bing, 20 results per page)
Both users share the same team API credentials
Each user may have different cache settings

Solution Architecture

The three-tier system addresses this by:

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

Database Schema

The three-tier configuration system uses three main tables:

Tier 1: MCP Catalog (`mcpServers`)

Defines configuration structure for each MCP server type including template-level config, team/user schemas, transport configuration, and registry tracking.

Tier 2: Team Installation (`mcpServerInstallations`)

Manages shared team configurations including installation name, team args, environment variables, headers, and URL query params.

Per-User Instances (`mcpServerInstances`)

While not strictly a “configuration tier”, the instance table enables per-user isolation: Key Characteristics:

One instance per user per installation (UNIQUE constraint)
Independent status tracking per user
CASCADE deletes when installation removed
Enables parallel status states (User A online, User B offline)

For complete database schema, see Database Schema. For complete instance lifecycle, see Instance Lifecycle.

Tier 3: User Configuration (`mcpUserConfigurations`)

Stores individual user configurations including personal args, environment variables, headers, and URL query params. For complete database schema details, see Database Schema.

Configuration Flow

Runtime Assembly

Per-User Instance Isolation: Configurations are assembled per user at runtime. Each team member’s instance receives their merged config (template + team + user).

Configuration Schema Step

Global administrators categorize configuration elements through the Configuration Schema Step:

Extract Elements: Parse Claude Desktop config for all args and env vars
Categorize Each Element: Assign to Template/Team/User tiers
Set Lock Controls: Define default_team_locked and visible_to_users
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

RegistrySyncService

Manages automatic synchronization with the official MCP Registry: Key Responsibilities:

Fetches server list from registry.modelcontextprotocol.io
Creates job queue batches for progress tracking
Schedules individual server sync jobs with rate limiting
Coordinates with McpServerSyncWorker for transformation

Sync Process:

Fetch servers from official registry (with pagination)
Filter out existing servers (if skipExisting enabled)
Create job batch for tracking
Create individual jobs with scheduled delays (rate limiting)
Job queue processes sequentially via McpServerSyncWorker

Configuration Options:

maxServers: Limit number of servers to sync (for testing)
skipExisting: Skip servers already in database
forceRefresh: Force refresh of existing servers
rateLimitDelay: Seconds between jobs (default: 2)

For complete job queue details, see Job Queue System.

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

Automatic Schema Transformation

When servers are synced from the official MCP Registry, their configurations are automatically transformed to the three-tier system:

Environment Variable Mapping

Registry Format → DeployStack Tiers:

Template Level: Fixed values provided in registry
Team Level: isRequired: true + isSecret: true → Encrypted team secrets
Team Level: isRequired: true + isSecret: false → Required team settings
User Level: isRequired: false → Optional personal preferences

Example Transformation: Official registry environment variables:

[
  {"name": "API_KEY", "isRequired": true, "isSecret": true},
  {"name": "DEBUG", "isRequired": false, "default": "false"}
]

Automatically mapped to:

API_KEY → team_env_schema (encrypted, default_team_locked: true, visible_to_users: false)
DEBUG → user_env_schema (unlocked, user-configurable)

Transport Detection

STDIO Servers (packages):

Command and package name → template_args (locked)
Runtime arguments → Team/user schemas based on registry metadata

HTTP/SSE Servers (remotes):

URL → template_env or embedded in remotes config (locked)
Authentication headers → team_headers_schema (secrets)
Optional headers → user_headers_schema (personal preferences)
API keys in URL query params → team_url_query_params_schema (secrets)
User preferences in query params → user_url_query_params_schema (customization)

The transformation layer (officialRegistryTransforms.ts) handles all automatic mapping without admin intervention.

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 Examples

Manual Server Schema

Configuration schema created manually by global administrator:

{
  "name": "Custom Company API",
  "transport_type": "stdio",
  "synced_from_official_registry": false,
  "template_args": [
    {"value": "-y", "locked": true, "description": ""},
    {"value": "@company/api-server", "locked": true, "description": ""}
  ],
  "team_env_schema": [
    {
      "name": "COMPANY_API_KEY",
      "type": "secret", 
      "required": true,
      "default_team_locked": true,
      "visible_to_users": false,
      "description": "Company API authentication key"
    }
  ],
  "user_env_schema": [
    {
      "name": "DEBUG_MODE",
      "type": "boolean",
      "required": false,
      "default": "false",
      "description": "Enable debug logging"
    }
  ]
}

Synced Server Schema

Configuration schema automatically transformed from official registry:

{
  "name": "Context7",
  "official_name": "io.github.upstash/context7",
  "transport_type": "stdio",
  "synced_from_official_registry": true,
  "official_registry_server_id": "srv_abc123",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "@upstash/context7",
      "transport": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@upstash/context7"]
      },
      "environmentVariables": [
        {
          "name": "UPSTASH_REDIS_URL",
          "isRequired": true,
          "isSecret": false
        },
        {
          "name": "UPSTASH_REDIS_TOKEN",
          "isRequired": true,
          "isSecret": true
        },
        {
          "name": "DEBUG",
          "isRequired": false,
          "default": "false"
        }
      ]
    }
  ],
  "template_args": [
    {"value": "-y", "locked": true},
    {"value": "@upstash/context7", "locked": true}
  ],
  "team_env_schema": [
    {
      "name": "UPSTASH_REDIS_URL",
      "type": "string",
      "required": true,
      "default_team_locked": true,
      "visible_to_users": true
    },
    {
      "name": "UPSTASH_REDIS_TOKEN",
      "type": "secret",
      "required": true,
      "default_team_locked": true,
      "visible_to_users": false
    }
  ],
  "user_env_schema": [
    {
      "name": "DEBUG",
      "type": "boolean",
      "required": false,
      "default": "false"
    }
  ],
  "github_stars": 142,
  "github_account_id": "12345678"
}

Key Differences:

Synced servers include official_name and registry tracking fields
Synced servers have packages array with original registry format preserved
Schema transformation is automatic based on isRequired and isSecret properties
GitHub metadata automatically populated during sync

For specific implementation details:

Backend API - Complete API endpoint documentation
Database Schema - Database structure and relationships
Job Queue System - Background job processing for registry sync
Teams - Team management and structure
MCP Configuration System - User-facing configuration guide
MCP Installation - Installation and team setup
MCP Catalog - Official registry integration details

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. The system seamlessly handles both manually created custom servers and automatically synced official registry servers.

Basics

Advanced

API

Database

Auth

Satellite

Server Sources

Official Registry Servers (Automatic)

Manual Servers (Custom)

Architecture Overview

Lock/Unlock Control System

Design Problem

The Multi-User Team Challenge

Solution Architecture

Database Schema

Tier 1: MCP Catalog (`mcpServers`)

Tier 2: Team Installation (`mcpServerInstallations`)

Per-User Instances (`mcpServerInstances`)

Tier 3: User Configuration (`mcpUserConfigurations`)

Configuration Flow

Runtime Assembly

Configuration Schema Step

Runtime Assembly

Service Layer

RegistrySyncService

McpUserConfigurationService

Automatic Schema Transformation

Environment Variable Mapping

Transport Detection

API Endpoints

API Endpoints

Schema Examples

Manual Server Schema

Synced Server Schema

Basics

Advanced

API

Database

Auth

Satellite

​Server Sources

​Official Registry Servers (Automatic)

​Manual Servers (Custom)

​Architecture Overview

​Lock/Unlock Control System

​Design Problem

​The Multi-User Team Challenge

​Solution Architecture

​Database Schema

​Tier 1: MCP Catalog (mcpServers)

​Tier 2: Team Installation (mcpServerInstallations)

​Per-User Instances (mcpServerInstances)

​Tier 3: User Configuration (mcpUserConfigurations)

​Configuration Flow

​Runtime Assembly

​Configuration Schema Step

​Runtime Assembly

​Service Layer

​RegistrySyncService

​McpUserConfigurationService

​Automatic Schema Transformation

​Environment Variable Mapping

​Transport Detection

​API Endpoints

​API Endpoints

​Schema Examples

​Manual Server Schema

​Synced Server Schema

​Related Documentation

Server Sources

Official Registry Servers (Automatic)

Manual Servers (Custom)

Architecture Overview

Lock/Unlock Control System

Design Problem

The Multi-User Team Challenge

Solution Architecture

Database Schema

Tier 1: MCP Catalog (`mcpServers`)

Tier 2: Team Installation (`mcpServerInstallations`)

Per-User Instances (`mcpServerInstances`)

Tier 3: User Configuration (`mcpUserConfigurations`)

Configuration Flow

Runtime Assembly

Configuration Schema Step

Runtime Assembly

Service Layer

RegistrySyncService

McpUserConfigurationService

Automatic Schema Transformation

Environment Variable Mapping

Transport Detection

API Endpoints

API Endpoints

Schema Examples

Manual Server Schema

Synced Server Schema

Related Documentation