​
Secrets

Secrets management in Pylee provides a secure way to handle sensitive information like API keys, passwords, tokens, and other confidential data. Rather than hardcoding these values in configuration files, Pylee offers multiple secure storage and retrieval mechanisms.

​
What are Secrets?

Secrets are sensitive pieces of information that should never be stored in plain text or committed to version control. In Pylee, secrets include:
  • API keys and tokens: Authentication credentials for external services
  • Database passwords: Connection credentials for databases
  • Certificates and keys: SSL/TLS certificates and private keys
  • Authentication tokens: OAuth tokens and session keys
  • Encryption keys: Keys used for data encryption and decryption

​
Secret Storage Options

​
Environment Variables

The simplest approach for storing secrets in environment variables: 
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

​
Secret References

Use special syntax to reference secrets stored in secure vaults: 
{
  "mcpServers": {
    "database": {
      "command": "python",
      "args": ["-m", "db_server"],
      "env": {
        "DATABASE_PASSWORD": "${secret:db_password}",
        "API_KEY": "${secret:external_api_key}"
      }
    }
  }
}

​
File-based Secrets

Store secrets in secure files with restricted permissions: 
{
  "mcpServers": {
    "api-server": {
      "command": "python",
      "args": ["-m", "api_server"],
      "env": {
        "API_KEY": "${file:/opt/secrets/api_key}",
        "JWT_SECRET": "${file:~/.pylee/secrets/jwt_secret}"
      }
    }
  }
}

​
Secret Providers

​
Local Secret Store

Pylee’s built-in encrypted secret storage: 
# Store a secret
pylee secret set api_key "your-secret-key"

# List stored secrets
pylee secret list

# Remove a secret
pylee secret remove api_key
Configuration usage: 
{
  "mcpServers": {
    "api-client": {
      "env": {
        "API_KEY": "${secret:api_key}"
      }
    }
  }
}

​
External Secret Managers

​
AWS Secrets Manager

{
  "secretProviders": {
    "aws": {
      "type": "aws-secrets-manager",
      "region": "us-east-1"
    }
  },
  "mcpServers": {
    "app": {
      "env": {
        "DATABASE_URL": "${aws:prod/database/connection-string}"
      }
    }
  }
}

​
HashiCorp Vault

{
  "secretProviders": {
    "vault": {
      "type": "hashicorp-vault",
      "address": "https://vault.company.com",
      "auth": {
        "method": "token",
        "token": "${VAULT_TOKEN}"
      }
    }
  },
  "mcpServers": {
    "app": {
      "env": {
        "API_KEY": "${vault:secret/data/api-keys#key}"
      }
    }
  }
}

​
Azure Key Vault

{
  "secretProviders": {
    "azure": {
      "type": "azure-keyvault",
      "vaultUrl": "https://myvault.vault.azure.net/"
    }
  },
  "mcpServers": {
    "app": {
      "env": {
        "CONNECTION_STRING": "${azure:database-connection-string}"
      }
    }
  }
}

​
Secret Syntax

​
Basic Secret Reference

{
  "env": {
    "API_KEY": "${secret:api_key}"
  }
}

​
Provider-specific References

{
  "env": {
    "AWS_SECRET": "${aws:prod/api-keys/external-service}",
    "VAULT_SECRET": "${vault:secret/data/config#password}",
    "AZURE_SECRET": "${azure:connection-string}"
  }
}

​
Secret with Default Values

{
  "env": {
    "API_TIMEOUT": "${secret:api_timeout:-30}"
  }
}

​
Complex Secret Structures

For JSON secrets: 
{
  "env": {
    "DATABASE_CONFIG": "${secret:db_config}",
    "DB_HOST": "${secret:db_config#host}",
    "DB_PORT": "${secret:db_config#port}"
  }
}

​
Security Best Practices

​
Access Control

  • Implement least-privilege access to secrets
  • Use role-based access control (RBAC)
  • Regularly audit secret access logs
  • Rotate secrets regularly

​
Storage Security

  • Never commit secrets to version control
  • Use encrypted storage for secret files
  • Set restrictive file permissions (600 or 400)
  • Store secrets separate from configuration

​
Network Security

  • Use HTTPS/TLS for secret transmission
  • Implement proper certificate validation
  • Use VPNs or private networks when possible
  • Monitor secret access patterns

​
Rotation and Lifecycle

  • Implement automatic secret rotation
  • Set expiration dates for secrets
  • Have rollback procedures for secret changes
  • Monitor for secret usage anomalies

​
Environment-Specific Secrets

​
Development Environment

{
  "environments": {
    "development": {
      "secretProviders": {
        "local": {
          "type": "local-store",
          "path": "~/.pylee/dev-secrets"
        }
      }
    }
  },
  "mcpServers": {
    "api": {
      "env": {
        "API_KEY": "${local:dev_api_key}",
        "DATABASE_URL": "postgresql://localhost:5432/dev"
      }
    }
  }
}

​
Production Environment

{
  "environments": {
    "production": {
      "secretProviders": {
        "vault": {
          "type": "hashicorp-vault",
          "address": "${VAULT_ADDR}",
          "auth": {
            "method": "kubernetes"
          }
        }
      }
    }
  },
  "mcpServers": {
    "api": {
      "env": {
        "API_KEY": "${vault:secret/prod/api-keys#external-service}",
        "DATABASE_URL": "${vault:secret/prod/database#connection-string}"
      }
    }
  }
}

​
Secret Templates

​
Database Connection Template

{
  "templates": {
    "database_connection": {
      "env": {
        "DB_HOST": "${secret:${service}_db_host}",
        "DB_PORT": "${secret:${service}_db_port}",
        "DB_USER": "${secret:${service}_db_user}",
        "DB_PASS": "${secret:${service}_db_password}",
        "DB_NAME": "${secret:${service}_db_name}"
      }
    }
  },
  "mcpServers": {
    "user-service": {
      "template": "database_connection",
      "variables": {
        "service": "user"
      }
    }
  }
}

​
API Client Template

{
  "templates": {
    "api_client": {
      "env": {
        "API_BASE_URL": "${secret:${service}_api_url}",
        "API_KEY": "${secret:${service}_api_key}",
        "API_TIMEOUT": "${secret:${service}_api_timeout:-30}"
      }
    }
  }
}

​
Secret Validation

​
Required Secrets

{
  "secrets": {
    "api_key": {
      "required": true,
      "description": "API key for external service",
      "type": "string",
      "pattern": "^sk-[a-zA-Z0-9]{32}$"
    },
    "database_password": {
      "required": true,
      "description": "Database connection password",
      "minLength": 12
    }
  }
}

​
Secret Encryption

{
  "secretStore": {
    "encryption": {
      "algorithm": "AES-256-GCM",
      "keyDerivation": "PBKDF2",
      "iterations": 100000
    }
  }
}

​
Advanced Features

​
Secret Injection at Runtime

{
  "mcpServers": {
    "dynamic-service": {
      "command": "python",
      "args": ["-m", "service"],
      "secretInjection": {
        "method": "file",
        "path": "/tmp/secrets",
        "format": "json",
        "secrets": [
          "api_key",
          "database_password"
        ]
      }
    }
  }
}

​
Secret Monitoring

{
  "secretMonitoring": {
    "enabled": true,
    "logAccess": true,
    "alertOnFailure": true,
    "rotationWarnings": {
      "enabled": true,
      "daysBefore": 7
    }
  }
}

​
Multi-Region Secrets

{
  "secretProviders": {
    "primary": {
      "type": "aws-secrets-manager",
      "region": "us-east-1"
    },
    "fallback": {
      "type": "aws-secrets-manager",
      "region": "us-west-2"
    }
  },
  "mcpServers": {
    "api": {
      "env": {
        "API_KEY": "${primary:api-key||fallback:api-key}"
      }
    }
  }
}

​
Troubleshooting

​
Common Issues

​
Secret Not Found

Error: Secret 'api_key' not found in provider 'local'
Solutions:
  • Verify secret exists: pylee secret list
  • Check provider configuration
  • Ensure proper access permissions

​
Permission Denied

Error: Access denied to secret 'database_password'
Solutions:
  • Check IAM/RBAC permissions
  • Verify authentication credentials
  • Review secret access policies

​
Secret Decryption Failed

Error: Failed to decrypt secret 'encrypted_token'
Solutions:
  • Verify encryption key is correct
  • Check secret store integrity
  • Ensure proper key permissions

​
Debugging Secrets

Enable secret debugging (be careful in production): 
{
  "debug": {
    "secrets": {
      "enabled": true,
      "maskValues": true,
      "logAccess": true
    }
  }
}

​
Integration Examples

​
Complete API Service Configuration

{
  "secretProviders": {
    "vault": {
      "type": "hashicorp-vault",
      "address": "${VAULT_ADDR}"
    }
  },
  "mcpServers": {
    "payment-service": {
      "command": "python",
      "args": ["-m", "payment_service"],
      "env": {
        "STRIPE_SECRET_KEY": "${vault:secret/payment/stripe#secret_key}",
        "STRIPE_WEBHOOK_SECRET": "${vault:secret/payment/stripe#webhook_secret}",
        "DATABASE_URL": "${vault:secret/payment/database#connection_string}",
        "JWT_SECRET": "${vault:secret/payment/auth#jwt_secret}",
        "ENCRYPTION_KEY": "${vault:secret/payment/encryption#master_key}"
      }
    }
  }
}

​
Multi-Environment Secret Management

{
  "environments": {
    "development": {
      "secretProviders": {
        "local": {
          "type": "local-store"
        }
      }
    },
    "staging": {
      "secretProviders": {
        "aws": {
          "type": "aws-secrets-manager",
          "region": "us-east-1",
          "prefix": "staging/"
        }
      }
    },
    "production": {
      "secretProviders": {
        "aws": {
          "type": "aws-secrets-manager",
          "region": "us-east-1",
          "prefix": "prod/"
        }
      }
    }
  }
}

​
Next Steps

  • Learn about Variables for non-sensitive configuration
  • Explore Server configuration for complete setup examples
  • Check the Troubleshooting guide for secret-related issues
  • Review security best practices for your deployment environment