> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pyleeai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Variables Configuration

> Configure and manage variables for dynamic server configuration without hardcoding sensitive information

# 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:

```json theme={null}
{
  "name": "API_BASE_URL",
  "value": "https://api.example.com",
  "is_required": true,
  "is_secret": false
}
```

### Secret Variables

Sensitive information that should be protected:

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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**

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

**Production Environment**

```json theme={null}
{
  "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:**

1. Navigate to Organization Settings
2. Select Variables or Secrets tab
3. Add new variables with appropriate scope
4. 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:**

1. Access registry configuration
2. Navigate to Variables or Secrets section
3. Define registry-specific values
4. 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

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

When troubleshooting variable resolution:

```json theme={null}
{
  "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:**

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

**Variable Renaming:**

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/Import:**

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

## Integration Examples

### CI/CD Pipeline

```yaml theme={null}
# 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

```dockerfile theme={null}
# 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](/understanding-pylee/remotes-configuration) for server communication
* [Configure packages](/understanding-pylee/packages-configuration) with variable references
* [Set up organization settings](/organization/settings) for variable management
* [Explore registry configuration](/registries/configuration) for shared variables

## Resources

* [Organization Variables Documentation](/organization/variables)
* [Registry Variables Documentation](/registries/variables)
* [Security Best Practices](/security/best-practices)
* [Environment Management Guide](/deployment/environments)