Variables

Variables in Pylee provide a flexible way to store and manage dynamic values across your MCP server configurations. They enable you to parameterize server settings, handle environment-specific configurations, and manage sensitive data securely.

What are Variables?

Variables are named placeholders that can store values and be referenced throughout your Pylee configuration. They help you:

Avoid repetition: Define values once and reuse them across multiple servers
Environment flexibility: Use different values for development, staging, and production
Dynamic configuration: Change server behavior without modifying configuration files
Template reusability: Create configuration templates that can be customized

Variable Types

Environment Variables

System-level variables that are available to all processes:

{
  "mcpServers": {
    "api-server": {
      "command": "python",
      "args": ["-m", "api_server"],
      "env": {
        "API_BASE_URL": "${API_BASE_URL}",
        "API_VERSION": "${API_VERSION}"
      }
    }
  }
}

Configuration Variables

Variables defined within your Pylee configuration for internal use:

{
  "variables": {
    "workspace_path": "/Users/dev/projects",
    "default_timeout": "30"
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${workspace_path}"
      ]
    }
  }
}

Runtime Variables

Variables that are computed or set during Pylee execution:

Current timestamp
User home directory
System information
Dynamic paths

Variable Syntax

Basic Substitution

Use ${VARIABLE_NAME} syntax to reference variables:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
      }
    }
  }
}

Default Values

Provide fallback values when variables might be undefined:

{
  "mcpServers": {
    "database": {
      "command": "python",
      "args": [
        "-m", "db_server",
        "--host", "${DB_HOST:-localhost}",
        "--port", "${DB_PORT:-5432}"
      ]
    }
  }
}

Nested Variables

Variables can reference other variables:

{
  "variables": {
    "project_root": "/opt/myapp",
    "data_dir": "${project_root}/data",
    "logs_dir": "${project_root}/logs"
  }
}

Built-in Variables

Pylee provides several built-in variables that are automatically available:

System Variables

${HOME}: User’s home directory
${USER}: Current username
${PWD}: Current working directory
${TMPDIR}: Temporary directory path

Pylee Variables

${PYLEE_CONFIG_DIR}: Pylee configuration directory
${PYLEE_VERSION}: Current Pylee version
${PYLEE_ENV}: Environment (development, production, etc.)

Example Usage

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${HOME}/Documents"
      ]
    },
    "logs": {
      "command": "python",
      "args": ["-m", "log_server", "${PYLEE_CONFIG_DIR}/logs"]
    }
  }
}

Configuration Examples

Development Environment

{
  "variables": {
    "env": "development",
    "debug_mode": "true",
    "workspace": "${HOME}/dev/workspace"
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${workspace}"
      ]
    },
    "api": {
      "command": "python",
      "args": ["-m", "api_server"],
      "env": {
        "ENVIRONMENT": "${env}",
        "DEBUG": "${debug_mode}",
        "API_URL": "http://localhost:3000"
      }
    }
  }
}

Production Environment

{
  "variables": {
    "env": "production",
    "debug_mode": "false",
    "data_path": "/opt/app/data"
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${data_path}"
      ]
    },
    "api": {
      "command": "python",
      "args": ["-m", "api_server"],
      "env": {
        "ENVIRONMENT": "${env}",
        "DEBUG": "${debug_mode}",
        "API_URL": "${PRODUCTION_API_URL}"
      }
    }
  }
}

Multi-Server Configuration

{
  "variables": {
    "base_path": "/opt/services",
    "common_timeout": "60",
    "log_level": "info"
  },
  "mcpServers": {
    "service-a": {
      "command": "python",
      "args": ["-m", "service_a", "--path", "${base_path}/service-a"],
      "env": {
        "TIMEOUT": "${common_timeout}",
        "LOG_LEVEL": "${log_level}"
      }
    },
    "service-b": {
      "command": "python",
      "args": ["-m", "service_b", "--path", "${base_path}/service-b"],
      "env": {
        "TIMEOUT": "${common_timeout}",
        "LOG_LEVEL": "${log_level}"
      }
    }
  }
}

Variable Precedence

Variables are resolved in the following order (highest to lowest precedence):

Command-line arguments: Variables passed via CLI flags
Environment variables: System environment variables
Configuration file variables: Variables defined in configuration files
Built-in variables: Pylee’s predefined variables
Default values: Fallback values specified in variable references

Advanced Usage

Conditional Variables

Use different values based on conditions:

{
  "variables": {
    "database_url": "${NODE_ENV:-development}" === "production" 
      ? "${PROD_DATABASE_URL}" 
      : "postgresql://localhost:5432/dev"
  }
}

Array Variables

Variables can contain arrays for multiple values:

{
  "variables": {
    "allowed_dirs": [
      "${HOME}/Documents",
      "${HOME}/Projects",
      "/tmp"
    ]
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem"
      ].concat("${allowed_dirs}")
    }
  }
}

Template Variables

Create reusable server templates:

{
  "templates": {
    "python_server": {
      "command": "python",
      "args": ["-m", "${module_name}"],
      "env": {
        "PYTHONPATH": "${python_path:-/opt/app}",
        "LOG_LEVEL": "${log_level:-info}"
      }
    }
  },
  "mcpServers": {
    "data_processor": {
      "template": "python_server",
      "variables": {
        "module_name": "data_processor",
        "python_path": "/opt/data-tools"
      }
    }
  }
}

Variable Validation

Type Validation

Ensure variables have the correct type:

{
  "variables": {
    "port": {
      "type": "number",
      "value": "${PORT:-8080}",
      "min": 1,
      "max": 65535
    },
    "enabled": {
      "type": "boolean",
      "value": "${FEATURE_ENABLED:-false}"
    }
  }
}

Required Variables

Mark variables as required:

{
  "variables": {
    "api_key": {
      "required": true,
      "description": "API key for external service"
    },
    "database_url": {
      "required": true,
      "description": "Database connection string"
    }
  }
}

Best Practices

Naming Conventions

Use descriptive names: database_connection_string instead of db_conn
Use consistent casing: snake_case for configuration variables
Group related variables: api_base_url, api_timeout, api_version

Organization

Group variables by purpose or service
Use comments to document variable usage
Keep sensitive variables separate from configuration

Documentation

Document required variables and their purposes
Provide example values
Explain variable relationships and dependencies

Security

Never commit sensitive variables to version control
Use environment variables for secrets
Implement proper access controls for configuration files

Troubleshooting

Common Issues

Undefined Variables

Error: Variable 'API_KEY' is not defined

Solution: Ensure the variable is set in environment or configuration

Circular References

Error: Circular reference detected in variable 'var_a'

Solution: Remove circular dependencies between variables

Type Mismatches

Error: Expected number for 'port', got string

Solution: Ensure variable values match expected types

Debugging Variables

Enable variable debugging to see resolution process:

{
  "debug": {
    "variables": true
  }
}

Integration with Secrets

Variables work seamlessly with Pylee’s secrets management:

{
  "variables": {
    "api_endpoint": "https://api.example.com/v1"
  },
  "mcpServers": {
    "api-client": {
      "command": "python",
      "args": ["-m", "api_client"],
      "env": {
        "API_ENDPOINT": "${api_endpoint}",
        "API_KEY": "${secret:api_key}"
      }
    }
  }
}

Next Steps

Learn about Secrets for sensitive data management
Explore Server configuration for advanced server setup
Check the Troubleshooting guide for common variable issues

​Variables

​What are Variables?

​Variable Types

​Environment Variables

​Configuration Variables

​Runtime Variables

​Variable Syntax

​Basic Substitution

​Default Values

​Nested Variables

​Built-in Variables

​System Variables

​Pylee Variables

​Example Usage

​Configuration Examples

​Development Environment

​Production Environment

​Multi-Server Configuration

​Variable Precedence

​Advanced Usage

​Conditional Variables

​Array Variables

​Template Variables

​Variable Validation

​Type Validation

​Required Variables

​Best Practices

​Naming Conventions

​Organization

​Documentation

​Security

​Troubleshooting

​Common Issues

​Undefined Variables

​Circular References

​Type Mismatches

​Debugging Variables

​Integration with Secrets

​Next Steps