MCP Schema Creation Workflow for Global Administrators

Global administrators manage MCP server schemas through two distinct paths: automatic synchronization from the official MCP Registry and manual creation for custom integrations. This workflow creates the foundation for DeployStack’s three-tier configuration system.

Two Paths to Catalog Servers

DeployStack supports adding MCP servers to the catalog through two methods:

Path 1: Official Registry Sync (Automatic)

Recommended for public MCP servers

Source: Synced automatically from registry.modelcontextprotocol.io
Schema Creation: Automatic transformation via background jobs
Configuration Mapping: Environment variables automatically categorized into three tiers
Maintenance: Updates sync automatically from registry
Effort: One-click sync operation

How it works: When you trigger a registry sync, the system automatically:

Fetches server data from the official registry
Transforms package/remote configurations to DeployStack format
Maps environment variables to appropriate tiers (template/team/user)
Enriches with GitHub metadata (README, stars, topics)
Stores in catalog ready for team installation

For details on the sync process, see MCP Catalog - Official Registry Integration.

Path 2: Manual Creation (Custom)

Required for custom integrations not in official registry

Source: Manually created by global administrators
Schema Creation: Sophisticated manual categorization process (this document)
Configuration Mapping: Precise control over every configuration element
Maintenance: Manual updates as needed
Effort: Complete four-step workflow with detailed categorization

When to use: Custom company integrations, private MCP servers, proprietary tools, or servers not yet in the official registry.

The rest of this document describes Path 2: Manual Creation for custom MCP servers that require the sophisticated schema categorization process.

Overview

When you manually add custom MCP servers to the catalog, you design the entire configuration experience by precisely categorizing every configuration element and setting sophisticated lock/unlock controls:

What stays locked forever (template elements like system commands, package names)
What teams can configure and control (team-level settings like API keys, shared credentials)
What users can always customize (user-level settings like local paths, personal preferences)
Lock/unlock defaults and visibility controls for each configurable element

For an overview of how the three-tier system works, see MCP Configuration System. To understand how official registry servers are automatically transformed, see MCP Catalog - Official Registry Integration.

The Four-Step Manual Creation Workflow

Manually adding a custom MCP server to the catalog follows this process:

Step 1: GitHub Repository     ──→ Link to source repository (optional for custom servers)
Step 2: Claude Desktop Config ──→ Input raw configuration JSON  
Step 3: Configuration Schema  ──→ **Categorize every element into three tiers with lock/unlock controls**
Step 4: Basic Info           ──→ Set name, description, category

Note: This manual workflow is for custom servers. Official registry servers are synced automatically with schema transformation handled by the system. Step 3 is the sophisticated categorization process where you transform raw configuration into the three-tier system with precise lock/unlock controls.

Step 1: GitHub Repository (Optional)

Repository URL - GitHub repository containing the MCP server (optional for custom servers)
Branch - Usually main or master
Sync Settings - Automatic vs manual synchronization

Note: For custom company integrations without public repositories, this step can be skipped.

Step 2: Claude Desktop Configuration

Input the raw Claude Desktop configuration for your custom MCP server:

{
  "mcpServers": {
    "web-search": {
      "command": "npx",
      "args": [
        "-y",
        "@brightdata/mcp-server-web-search"
      ],
      "env": {
        "API_KEY": "your-api-key-here",
        "SEARCH_QUOTA": "1000"
      }
    }
  }
}

The system extracts all arguments and environment variables for manual categorization.

**For Official Registry Servers**: This extraction and categorization happens automatically during the sync process. The system reads `environmentVariables[]` from the registry format and maps them to appropriate tiers based on `isRequired` and `isSecret` properties.

### Step 3: Configuration Schema Definition (Manual)

For custom servers, you manually categorize every argument and environment variable from the Claude Desktop config into one of three tiers with sophisticated lock/unlock controls - this determines exactly what teams and users can configure.

**Comparison to Official Registry Servers**:

| Aspect | Manual Creation (Custom) | Official Registry (Synced) |
|--------|-------------------------|---------------------------|
| Schema Creation | Manual categorization by admin | Automatic transformation |
| Environment Variables | Admin decides tier placement | Auto-mapped by `isRequired`/`isSecret` |
| Arguments | Admin categorizes each arg | Auto-extracted from packages/remotes |
| Lock/Unlock Defaults | Admin sets defaults | Intelligent defaults based on registry |
| Effort | 15-30 minutes per server | Instant (background job) |

### Step 4: Basic Information

- **Server Name** - Display name in catalog
- **Description** - Clear explanation of functionality
- **Category** - Organizational classification

## Automatic Registry Server Transformation

When servers are synced from the official MCP Registry, the transformation happens automatically:

### Automatic Environment Variable Mapping

**Registry Format:**
```json
{
  "environmentVariables": [
    {
      "name": "UPSTASH_REDIS_URL",
      "isRequired": true,
      "isSecret": false
    },
    {
      "name": "UPSTASH_REDIS_TOKEN",
      "isRequired": true,
      "isSecret": true
    },
    {
      "name": "DEBUG",
      "isRequired": false,
      "default": "false"
    }
  ]
}

Automatic Tier Mapping:

Template Level: Fixed values (if 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

Result: The synced server works immediately with the three-tier system without any manual schema work.

Automatic Transport Detection

STDIO Servers (packages):

{
  "packages": [{
    "transport": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7"]
    }
  }]
}

Command and package name → Template level (locked)
Runtime args → Team/user level based on registry metadata

HTTP/SSE Servers (remotes):

{
  "remotes": [{
    "type": "sse",
    "url": "https://api.example.com/mcp",
    "headers": [...]
  }]
}

URL → Template level (locked)
Headers → Team/user level based on authentication requirements

For complete details on automatic transformation, see the Official Registry Integration documentation.

Step 3: Configuration Schema Definition for Manual Servers (Detailed)

The Sophisticated Categorization Process (Manual Servers Only)

For custom MCP servers created manually, you make precise categorization decisions with lock/unlock controls for every argument and environment variable extracted from the Claude Desktop config: Categorization Options:

🔒 Template (Static) - Locked forever, never changes (system commands, package names)
🔧 Team Configurable - Teams set values during installation and control user access
🔓 User Configurable - Always available for individual user customization

Lock/Unlock Controls:

Default Lock State - Whether teams start with elements locked or unlocked for users
Visibility Controls - Whether users can see values (important for secrets)
Schema Validation - Data types, requirements, and constraints for each element

This sophisticated system determines the exact configuration experience for teams and users. Note: Official registry servers receive automatic categorization based on their registry metadata, eliminating this manual process.

Example: Web Search MCP Server

Raw Configuration:

{
  "mcpServers": {
    "web-search": {
      "command": "npx",
      "args": [
        "-y",
        "@brightdata/mcp-server-web-search"
      ],
      "env": {
        "API_KEY": "your-api-key-here",
        "SEARCH_QUOTA": "1000",
        "DEFAULT_ENGINE": "google"
      }
    }
  }
}

Your Manual Categorization:

🔒 Template: -y and @brightdata/mcp-server-web-search (system commands, locked forever)
🔧 Team Configurable: API_KEY and SEARCH_QUOTA (shared credentials and limits)
🔓 User Configurable: DEFAULT_ENGINE (personal search preference, default unlocked)

If This Were an Official Registry Server: The system would automatically categorize based on registry metadata:

API_KEY with isRequired: true, isSecret: true → Team level (encrypted)
SEARCH_QUOTA with isRequired: true → Team level
DEFAULT_ENGINE with isRequired: false → User level

Lock/Unlock Decisions:

API credentials: Default locked for users, hidden from users (security)
Search quota: Default locked for users, visible to users (team resource management)
Search engine: Default unlocked (users can customize their preference)
Validation: API key must be valid format, quota must be positive number

Result: Teams manage shared API credentials and usage quotas, but users can customize their search engine preferences.

Another Example: API MCP Server with Secrets

Raw Configuration:

{
  "mcpServers": {
    "api": {
      "command": "npx",
      "args": ["-y", "@company/api-server"],
      "env": {
        "TEAM_API_KEY": "team-secret",
        "DEBUG": "false"
      }
    }
  }
}

Your Manual Categorization:

🔒 Template: System commands (npx, -y, package name) - locked forever
🔧 Team Configurable: TEAM_API_KEY (shared credential, team controls access)
🔓 User Configurable: DEBUG (personal preference, always available to users)

If From Official Registry: Would be automatically mapped:

TEAM_API_KEY with isRequired: true, isSecret: true → Team level (encrypted, hidden)
DEBUG with isRequired: false → User level (unlocked)

Lock/Unlock Decisions:

TEAM_API_KEY: Default locked for users, hidden from users (security)
DEBUG: Default unlocked for users, visible to users (personal preference)
Validation: API key must be valid format, debug must be boolean

Result: Teams manage shared API keys securely, users can toggle debug mode.

Smart Suggestions

DeployStack provides suggestions to help with categorization: 🔒 Template Suggestions:

CLI commands (npx, python, node)
Package names (@modelcontextprotocol/server-*)
System flags (-y, --verbose)

🔧 Team Configurable Suggestions:

Variables containing “team”, “api”, “key”
Database connection strings
Service endpoints

🔓 User Configurable Suggestions:

Search preferences and result formatting
Cache and performance settings
Personal API preferences

Configuration Schema Step Interface (Manual Creation)

The Configuration Schema Step presents a sophisticated interface for manually categorizing and controlling every configuration element:

Arguments Categorization Interface

Extracted Arguments from Claude Desktop Config:
┌─────────────────────────────────────────────────────────────────────────────┐
│ [0] "-y"                                                                   │
│     Configuration Level: Template (Static) ▼                               │
│     ✓ Locked Forever (Cannot be changed by teams or users)                │
│                                                                             │
│ [1] "@brightdata/mcp-server-web-search"                                   │
│     Configuration Level: Template (Static) ▼                               │
│     ✓ Locked Forever (Cannot be changed by teams or users)                │
│                                                                             │
│ [+] Add team-configurable argument                                          │
│ [+] Add user-configurable argument                                          │
└─────────────────────────────────────────────────────────────────────────────┘

Environment Variables Categorization Interface

Extracted Environment Variables from Claude Desktop Config:
┌─────────────────────────────────────────────────────────────────────────────┐
│ API_KEY: "your-api-key-here"                                                │
│ Configuration Level: Team Configurable ▼                                   │
│ ├─ Type: Secret ▼                                                          │
│ ├─ Required: ✓                                                             │
│ ├─ Description: BrightData API authentication key                           │
│ ├─ ✓ Default Team Locked (Users cannot modify)                             │
│ └─ ✓ Hidden from Users (Recommended for API keys)                          │
│                                                                             │
│ SEARCH_QUOTA: "1000"                                                        │
│ Configuration Level: Team Configurable ▼                                   │
│ ├─ Type: Number ▼                                                          │
│ ├─ Required: ✓                                                             │
│ ├─ Description: Daily search query limit                                    │
│ ├─ ✓ Default Team Locked (Teams control resource limits)                   │
│ └─ ☐ Hidden from Users (Users can see their quota limits)                  │
│                                                                             │
│ DEFAULT_ENGINE: "google"                                                    │
│ Configuration Level: User Configurable ▼                                   │
│ ├─ Type: String ▼                                                          │
│ ├─ Required: ☐                                                             │
│ ├─ Description: Preferred search engine                                     │
│ └─ ☐ Default Team Locked (Recommended: Unlocked for user preference)      │
│                                                                             │
│ [+] Add team-configurable environment variable                              │
│ [+] Add user-configurable environment variable                              │
└─────────────────────────────────────────────────────────────────────────────┘

Lock/Unlock Control Matrix

Your categorization decisions create a sophisticated control matrix across all three tiers:

Configuration Element	Global Admin Control	Team Admin Control	User Access
Template Args (Locked)	Define & Lock Forever	❌ Cannot Change	❌ Cannot Change
Template Env (Locked)	Define & Lock Forever	❌ Cannot Change	❌ Cannot Change
Team Args Schema	Define Schema & Defaults	Set Values & Lock/Unlock	Access if Unlocked
Team Env Schema	Define Schema & Defaults	Set Values & Lock/Unlock	Access if Unlocked
User Args Schema	Define Schema & Defaults	✓ Always Available	✓ Always Available
User Env Schema	Define Schema & Defaults	✓ Always Available	✓ Always Available
Additional Team Config	Define Limits	Add Custom Config	❌ Cannot Change
Additional User Config	Define Limits	✓ Allow/Disallow	Add Personal Config

This matrix shows how your schema categorization creates precise boundaries for configuration control.

What Happens Next

After you complete the sophisticated schema categorization for manual servers:

Schema Generation - System creates the complete three-tier schema structure with lock/unlock metadata
Catalog Addition - MCP server is added to the global catalog with precise configuration boundaries
Team Access - Teams can install and configure only the elements you designated as team-configurable
User Experience - Users see only the elements you made available, with lock/unlock states controlled by teams

For Official Registry Servers: This process happens automatically during sync, with schemas generated from registry metadata. Your categorization and lock/unlock decisions directly shape how teams and users interact with the MCP server across the entire three-tier system.

Security Validation

The system automatically validates schema categorization for both manual and synced servers: Security Checks:

✅ Secrets properly categorized as team/user level with appropriate visibility controls
✅ System commands locked at template level to prevent tampering
⚠️ Warns if secrets might be visible inappropriately or unlocked by default
✅ Validates lock inheritance logic across all three tiers

For Official Registry Servers: Security validation happens automatically during the transformation process, ensuring registry metadata is properly interpreted. Schema Validation:

✅ All extracted elements are properly categorized
✅ Required fields have appropriate defaults and validation rules
✅ Lock/unlock inheritance makes logical sense across tiers
✅ Data types and constraints are properly defined

Preview Capabilities:

See exactly what team administrators will configure during installation
Preview what users will be able to customize based on team lock/unlock decisions
Understand the complete configuration flow from admin → team → user
Validate the security model with real-world scenarios

Key Benefits

The schema system (whether manual or automatic) provides: Security - Sensitive data properly protected at the right tier with appropriate visibility controls Precision - Users see only what they can configure, teams control exactly what they need Flexibility - Teams can lock/unlock elements based on their specific organizational needs Consistency - Predictable configuration experience across all MCP servers in the catalog Governance - Complete audit trail and control over configuration inheritance across all tiers Automation - Official registry servers get instant schema transformation without manual work For understanding how schemas work across the system:

MCP Configuration System - Overview of the three-tier system schemas enable
MCP Catalog - Official Registry Integration - How automatic schema transformation works
Team Installation - How teams use schemas to configure installations
User Configuration - How users interact with schema boundaries
MCP Catalog - Where schemas are stored and managed

The schema creation system—whether through sophisticated manual categorization or automatic registry transformation—is the foundation that enables secure, flexible MCP server configuration with precise control over configuration inheritance across all teams and users.

Essentials

MCP Server

MCP Server Configuration

MCP Schema Creation Workflow for Global Administrators

MCP Schema Creation Workflow for Global Administrators

Two Paths to Catalog Servers

Path 1: Official Registry Sync (Automatic)

Path 2: Manual Creation (Custom)

Overview

The Four-Step Manual Creation Workflow

Step 1: GitHub Repository (Optional)

Step 2: Claude Desktop Configuration

Automatic Transport Detection

Step 3: Configuration Schema Definition for Manual Servers (Detailed)

The Sophisticated Categorization Process (Manual Servers Only)

Example: Web Search MCP Server

Another Example: API MCP Server with Secrets

Smart Suggestions

Configuration Schema Step Interface (Manual Creation)

Arguments Categorization Interface

Environment Variables Categorization Interface

Lock/Unlock Control Matrix

What Happens Next

Security Validation

Key Benefits

Essentials

MCP Server

MCP Server Configuration

​MCP Schema Creation Workflow for Global Administrators

​Two Paths to Catalog Servers

​Path 1: Official Registry Sync (Automatic)

​Path 2: Manual Creation (Custom)

​Overview

​The Four-Step Manual Creation Workflow

​Step 1: GitHub Repository (Optional)

​Step 2: Claude Desktop Configuration

​Automatic Transport Detection

​Step 3: Configuration Schema Definition for Manual Servers (Detailed)

​The Sophisticated Categorization Process (Manual Servers Only)

​Example: Web Search MCP Server

​Another Example: API MCP Server with Secrets

​Smart Suggestions

​Configuration Schema Step Interface (Manual Creation)

​Arguments Categorization Interface

​Environment Variables Categorization Interface

​Lock/Unlock Control Matrix

​What Happens Next

​Security Validation

​Key Benefits

​Related Documentation

MCP Schema Creation Workflow for Global Administrators

Two Paths to Catalog Servers

Path 1: Official Registry Sync (Automatic)

Path 2: Manual Creation (Custom)

Overview

The Four-Step Manual Creation Workflow

Step 1: GitHub Repository (Optional)

Step 2: Claude Desktop Configuration

Automatic Transport Detection

Step 3: Configuration Schema Definition for Manual Servers (Detailed)

The Sophisticated Categorization Process (Manual Servers Only)

Example: Web Search MCP Server

Another Example: API MCP Server with Secrets

Smart Suggestions

Configuration Schema Step Interface (Manual Creation)

Arguments Categorization Interface

Environment Variables Categorization Interface

Lock/Unlock Control Matrix

What Happens Next

Security Validation

Key Benefits

Related Documentation