​

Server Versions

Server versions allow you to track and manage different releases of your MCP servers over time. This enables you to maintain multiple versions of a server for different environments, rollback to previous versions, and coordinate deployments across your organization.

​

What are Server Versions?

Server versions are numbered releases of your MCP servers that provide:

• Version Control: Track changes and evolution of your servers
• Environment Management: Deploy different versions to different environments
• Rollback Capability: Quickly revert to previous working versions
• Team Coordination: Share specific versions across your organization
• Release Management: Organize and document server releases

​

Version Numbering

Pylee uses semantic versioning (semver) for server versions:

​

Semantic Versioning Format

MAJOR.MINOR.PATCH

• MAJOR: Incompatible API changes
• MINOR: Backwards-compatible functionality additions
• PATCH: Backwards-compatible bug fixes

​

Examples

• 1.0.0 - Initial release
• 1.0.1 - Bug fix release
• 1.1.0 - New feature release
• 2.0.0 - Breaking changes release

​

Version Suggestions

When creating a new server version, Pylee automatically suggests the next logical version number based on your existing versions:

• If no versions exist: 1.0.0
• For patch updates: increment the patch number (e.g., 1.0.0 → 1.0.1)
• For minor updates: increment the minor number (e.g., 1.0.5 → 1.1.0)
• For major updates: increment the major number (e.g., 1.5.3 → 2.0.0)

​

Creating Server Versions

​

Prerequisites

Before creating a server version, ensure you have:

• A server registered in your organization
• Appropriate permissions to create versions
• Your server code ready for release

​

Version Creation Process

1. Navigate to Server: Go to your server’s page in the Pylee dashboard
2. Create New Version: Click “Create New Version” or navigate to the versions section
3. Select Organization: Choose which organization will own this version
4. Enter Version Number: Provide a semantic version number
5. Review and Create: Confirm the version details and create

​

Version Validation

Pylee validates version numbers to ensure:

• Unique Versions: No duplicate versions within the same organization
• Valid Format: Follows semantic versioning conventions
• Logical Progression: Versions make sense in sequence

​

Managing Server Versions

​

Version Listing

View all versions of a server with details including:

• Version number
• Release date
• Organization ownership
• Current deployment status

​

Version Comparison

Compare different versions to understand:

• Changes between versions
• Feature additions or removals
• Configuration differences
• Performance improvements

​

Version Metadata

Each version stores important metadata:

• Creation Date: When the version was created
• Creator: Who created the version
• Organization: Which organization owns it
• Release Notes: Documentation of changes
• Deployment Status: Where it’s currently deployed

​

Version Deployment

​

Environment-Specific Deployment

Deploy different versions to different environments:

{
  "environments": {
    "development": {
      "server": "my-server",
      "version": "1.2.0-beta.1"
    },
    "staging": {
      "server": "my-server",
      "version": "1.1.5"
    },
    "production": {
      "server": "my-server",
      "version": "1.1.4"
    }
  }
}

​

Gradual Rollout

Implement gradual rollouts:

1. Development: Deploy and test new version
2. Staging: Validate in staging environment
3. Canary: Deploy to small subset of production
4. Production: Full production deployment

​

Rollback Strategy

Quickly rollback to previous versions:

• Immediate Rollback: Revert to last known good version
• Selective Rollback: Rollback specific environments
• Staged Rollback: Gradually rollback across environments

​

Version Organization

​

Multi-Organization Support

Server versions can be owned by different organizations:

• Shared Servers: Multiple organizations using the same server
• Organization-Specific Versions: Custom versions for specific organizations
• Version Inheritance: Base versions with organization-specific modifications

​

Organization Context

When creating versions, consider:

• Target Organization: Which organization will own the version
• Access Permissions: Who can deploy and manage the version
• Resource Allocation: Organization-specific resource limits

​

Best Practices

​

Version Naming

Follow consistent naming conventions:

• Use semantic versioning
• Include pre-release identifiers when appropriate
• Consider branch-based versioning for development

​

Release Planning

Plan your releases effectively:

• Feature Branches: Develop features in separate branches
• Version Branches: Maintain stable version branches
• Hotfix Branches: Quick fixes for production issues

​

Documentation

Document your versions thoroughly:

• Release Notes: What changed in each version
• Migration Guides: How to upgrade between versions
• Breaking Changes: Incompatible changes and workarounds

​

Testing Strategy

Test versions comprehensively:

• Unit Tests: Test individual components
• Integration Tests: Test server integration
• Performance Tests: Validate performance characteristics
• Compatibility Tests: Ensure backwards compatibility

​

Version Lifecycle

​

Development Phase

• Create development versions
• Test new features and fixes
• Iterate based on feedback

​

Release Phase

• Create release candidate versions
• Perform final testing
• Create stable release version

​

Maintenance Phase

• Monitor version performance
• Apply security patches
• Plan deprecation timeline

​

Deprecation Phase

• Announce deprecation timeline
• Provide migration path
• Remove deprecated versions

​

Advanced Features

​

Version Tagging

Use tags to mark special versions:

• latest - Most recent stable version
• lts - Long-term support version
• beta - Beta release version
• alpha - Alpha release version

​

Version Branching

Maintain multiple version branches:

• Master Branch: Latest development
• Release Branches: Stable releases
• Hotfix Branches: Critical fixes

​

Version Automation

Automate version management:

• CI/CD Integration: Automatic version creation
• Deployment Automation: Automated deployment pipelines
• Version Monitoring: Monitor version health

​

Troubleshooting

​

Version Creation Issues

Common problems and solutions:

• Duplicate Version: Choose a different version number
• Invalid Format: Use semantic versioning format
• Permission Denied: Ensure you have version creation permissions

​

Deployment Issues

Resolve deployment problems:

• Version Not Found: Verify version exists and is accessible
• Compatibility Issues: Check version compatibility
• Resource Conflicts: Resolve resource allocation conflicts

​

Performance Issues

Optimize version performance:

• Version Size: Keep versions lightweight
• Startup Time: Optimize server startup
• Memory Usage: Monitor memory consumption

​

Integration with CI/CD

​

Automated Version Creation

Integrate with your CI/CD pipeline:

name: Create Version
on:
  push:
    tags:
      - 'v*'

jobs:
  create-version:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Create Pylee Version
        run: |
          pylee server version create \
            --server=${{ env.SERVER_NAME }} \
            --version=${{ github.ref_name }} \
            --organization=${{ env.ORG_ID }}

​

Deployment Automation

Automate version deployment:

name: Deploy Version
on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Version to deploy'
        required: true
      environment:
        description: 'Target environment'
        required: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy Version
        run: |
          pylee server deploy \
            --server=${{ env.SERVER_NAME }} \
            --version=${{ inputs.version }} \
            --environment=${{ inputs.environment }}

​

Security Considerations

​

Version Access Control

Control access to versions:

• Read Permissions: Who can view versions
• Write Permissions: Who can create versions
• Deploy Permissions: Who can deploy versions

​

Version Signing

Sign versions for integrity:

• Digital Signatures: Verify version authenticity
• Checksum Validation: Ensure version integrity
• Audit Trail: Track version changes

​

Sensitive Data

Protect sensitive information:

• Environment Variables: Secure configuration
• API Keys: Protect authentication credentials
• Database Connections: Secure database access

​

Migration and Upgrades

​

Version Migration

Migrate between versions safely:

1. Backup Current State: Save current configuration
2. Test Migration: Test in non-production environment
3. Execute Migration: Apply version changes
4. Verify Results: Confirm migration success

​

Upgrade Strategies

Choose appropriate upgrade strategies:

• Blue-Green Deployment: Zero-downtime upgrades
• Rolling Updates: Gradual version rollout
• Canary Deployment: Test with subset of traffic

​

Monitoring and Observability

​

Version Metrics

Monitor version performance:

• Deployment Success Rate: Track deployment success
• Error Rates: Monitor version-specific errors
• Performance Metrics: Track response times and throughput

​

Health Checks

Implement version health checks:

• Startup Checks: Verify version starts correctly
• Runtime Checks: Monitor ongoing health
• Dependency Checks: Verify external dependencies

​

Next Steps

• Learn about Organizations to understand version ownership
• Explore Servers for server management basics
• Check Variables for version-specific configuration
• Review Troubleshooting for common issues