​

Variables Configuration

​

Overview

• Avoid hardcoded secrets in configuration files
• Support multiple environments with the same configuration template
• Centralize configuration management across your organization
• Provide runtime flexibility through user prompts when needed

​

Variable Syntax

{variable_name}

​

Examples

Bearer {api_token}

postgresql://{db_user}:{db_password}@{db_host}:5432/{db_name}

https://{api_base_url}/v1/endpoints

​

Variable Resolution Order

​

1. Organization Variables or Secrets

• Variables: Non-sensitive configuration values
• Secrets: Sensitive information like API keys and passwords
• Scope: Available to all servers within the organization
• Access: Managed through organization settings

​

2. Registry Variables or Secrets

• Variables: Registry-specific configuration values
• Secrets: Registry authentication tokens and credentials
• Scope: Available to all servers using the specific registry
• Access: Managed through registry configuration

​

3. User Prompt

• Interactive: Prompts appear during server initialization
• Required Variables: Must be provided or execution fails
• Optional Variables: Can be skipped if not required
• Session Storage: Values may be cached for the session

​

Variable Types

​

Regular Variables

{
  "name": "API_BASE_URL",
  "value": "https://api.example.com",
  "is_required": true,
  "is_secret": false
}

​

Secret Variables

{
  "name": "API_KEY",
  "value": "",
  "is_required": true,
  "is_secret": true
}

• Values are masked in logs and UI
• Stored in secure, encrypted storage
• Access is logged and audited
• Cannot be retrieved once set (write-only)

​

Configuration Examples

​

Authentication Configuration

{
  "headers": [
    {
      "name": "Authorization",
      "value": "Bearer {github_token}",
      "description": "GitHub API authentication token",
      "is_required": true,
      "is_secret": true
    },
    {
      "name": "User-Agent",
      "value": "Pylee/{version}",
      "description": "Client identification header",
      "is_required": false,
      "is_secret": false
    }
  ]
}

​

Database Configuration

{
  "environment_variables": [
    {
      "name": "DATABASE_URL",
      "value": "postgresql://{db_user}:{db_password}@{db_host}:5432/{db_name}",
      "is_required": true,
      "is_secret": true
    },
    {
      "name": "DB_POOL_SIZE",
      "value": "{max_connections}",
      "is_required": false,
      "is_secret": false
    }
  ]
}

​

Multi-Environment Setup

{
  "url": "https://{dev_api_host}/mcp",
  "headers": [
    {
      "name": "Authorization",
      "value": "Bearer {dev_token}",
      "is_required": true,
      "is_secret": true
    }
  ]
}

{
  "url": "https://{prod_api_host}/mcp",
  "headers": [
    {
      "name": "Authorization",
      "value": "Bearer {prod_token}",
      "is_required": true,
      "is_secret": true
    }
  ]
}

​

Managing Variables

​

Organization Level

1. Navigate to Organization Settings
2. Select Variables or Secrets tab
3. Add new variables with appropriate scope
4. Configure access permissions

• Use organization variables for global settings
• Keep environment-agnostic values at this level
• Examples: company API endpoints, shared configurations

​

Registry Level

1. Access registry configuration
2. Navigate to Variables or Secrets section
3. Define registry-specific values
4. Configure inheritance rules

• Use for registry-specific authentication
• Configure shared credentials for registry access
• Examples: npm tokens, PyPI credentials, Docker registry auth

​

Variable Naming Conventions

API_KEY           # Simple, descriptive name
DB_PASSWORD       # Clear purpose indication
GITHUB_TOKEN      # Service-specific naming
MAX_CONNECTIONS   # Configuration parameter

key1              # Ambiguous naming
temp_var          # Temporary-sounding names
x                 # Single character names

​

Security Best Practices

​

Secret Management

• Mark sensitive variables as secrets
• Use descriptive names for secrets
• Rotate secrets regularly
• Limit access to secrets

• Store secrets in regular variables
• Use secrets for non-sensitive data
• Share secret values in plain text
• Hardcode secrets in configurations

​

Access Control

• Limit to administrators and trusted users
• Audit access and modifications
• Use role-based permissions

• Scope to specific registries
• Grant access based on need
• Monitor usage patterns

​

Troubleshooting

​

Common Issues

• Check variable name spelling
• Verify variable exists at the expected level
• Confirm access permissions
• Review resolution order

• Verify user has access to the variable scope
• Check organization or registry permissions
• Confirm secret access rights

• Ensure variable is marked as required
• Check if value exists at higher levels
• Verify client supports interactive prompts

​

Debugging Steps

1. Verify Variable Reference
   • Check bracket syntax: {variable_name}
   • Confirm no typos in variable name
   • Validate configuration format
2. Check Resolution Path
   • Look for organization-level variables
   • Verify registry-level variables
   • Confirm user prompt behavior
3. Test Access Permissions
   • Try accessing the variable directly
   • Check user role permissions
   • Verify scope restrictions

​

Debug Information

{
  "variable_name": "api_token",
  "resolution_path": [
    {
      "level": "organization",
      "found": false,
      "reason": "Variable not defined"
    },
    {
      "level": "registry",
      "found": true,
      "source": "registry_secrets"
    }
  ],
  "final_value": "[REDACTED]",
  "is_secret": true
}

​

Migration and Updates

​

Variable Updates

1. Navigate to the appropriate scope (organization/registry)
2. Locate the variable to update
3. Modify the value (secrets require re-entry)
4. Save changes and verify propagation

1. Create new variable with desired name
2. Update all references in configurations
3. Test with new variable name
4. Remove old variable once confirmed

​

Bulk Operations

• Export variables for backup
• Import variables across environments
• Bulk update through configuration files
• Maintain security for secret variables

​

Integration Examples

​

CI/CD Pipeline

# GitHub Actions example
name: Deploy MCP Server
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Configure variables
        env:
          PROD_API_TOKEN: ${{ secrets.PROD_API_TOKEN }}
          PROD_DB_HOST: ${{ vars.PROD_DB_HOST }}
        run: |
          # Variables will be resolved at runtime
          pylee deploy --config production.json

​

Docker Deployment

# Variables resolved at container runtime
ENV API_BASE_URL={api_host}
ENV DATABASE_URL=postgresql://{db_user}:{db_password}@{db_host}:5432/{db_name}
ENV DEBUG_MODE={debug_enabled}

​

Best Practices Summary

​

Configuration Design

• Use descriptive variable names that clearly indicate purpose
• Separate secrets from regular variables using appropriate flags
• Minimize variable scope to the most specific level needed
• Document variable purpose with clear descriptions

​

Security

• Never store actual secrets in configuration files
• Use the secret flag for all sensitive information
• Rotate secrets regularly and update references
• Audit variable access and modifications

​

Operations

• Test variable resolution in development environments
• Monitor variable usage across deployments
• Maintain variable documentation for team members
• Plan for variable migration during system updates

​

Next Steps

• Learn about remote connections for server communication
• Configure packages with variable references
• Set up organization settings for variable management
• Explore registry configuration for shared variables

​

Resources

• Organization Variables Documentation
• Registry Variables Documentation
• Security Best Practices
• Environment Management Guide