Variables Configuration

Variables in Pylee allow for dynamic configuration without hardcoding sensitive information or environment-specific values. They provide a flexible way to manage configuration across different environments and deployment scenarios.

Overview

Variables enable you to:

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

Variables are referenced using bracket notation ({variable_name}) in your configuration templates and are resolved at runtime through a hierarchical lookup system.

Variable Syntax

Variables are referenced using curly braces around the variable name:

{variable_name}

Examples

Authentication Header

Bearer {api_token}

Database Connection String

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

API Endpoint

https://{api_base_url}/v1/endpoints

Variable Resolution Order

When a variable is referenced, Pylee resolves its value by checking the following sources in order:

1. Organization Variables or Secrets

Global settings for your organization that apply across all servers and registries.

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

Shared configuration across servers that use the same registry.

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

When no value is found in the previous sources, users are prompted to provide the value at runtime.

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

Non-sensitive configuration values that can be displayed in logs and UI:

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

Secret Variables

Sensitive information that should be protected:

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

Secret Variable Characteristics:

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

Development Environment

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

Production Environment

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

Managing Variables

Organization Level

Setting Organization Variables:

Navigate to Organization Settings
Select Variables or Secrets tab
Add new variables with appropriate scope
Configure access permissions

Best Practices:

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

Registry Level

Setting Registry Variables:

Access registry configuration
Navigate to Variables or Secrets section
Define registry-specific values
Configure inheritance rules

Best Practices:

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

Variable Naming Conventions

Recommended Patterns:

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

Avoid:

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

Security Best Practices

Secret Management

Do:

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

Don’t:

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

Access Control

Organization Secrets:

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

Registry Secrets:

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

Troubleshooting

Common Issues

Variable Not Resolving

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

Permission Denied

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

Prompt Not Appearing

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

Debugging Steps

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

Debug Information

When troubleshooting variable resolution:

{
  "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

Updating Variable Values:

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

Variable Renaming:

Create new variable with desired name
Update all references in configurations
Test with new variable name
Remove old variable once confirmed

Bulk Operations

Export/Import:

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

After configuring variables:

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

​Variables Configuration

​Overview

​Variable Syntax

​Examples

​Variable Resolution Order

​1. Organization Variables or Secrets

​2. Registry Variables or Secrets

​3. User Prompt

​Variable Types

​Regular Variables

​Secret Variables

​Configuration Examples

​Authentication Configuration

​Database Configuration

​Multi-Environment Setup

​Managing Variables

​Organization Level

​Registry Level

​Variable Naming Conventions

​Security Best Practices

​Secret Management

​Access Control

​Troubleshooting

​Common Issues

​Debugging Steps

​Debug Information

​Migration and Updates

​Variable Updates

​Bulk Operations

​Integration Examples

​CI/CD Pipeline

​Docker Deployment

​Best Practices Summary

​Configuration Design

​Security

​Operations

​Next Steps

​Resources