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

​Secrets

​What are Secrets?

​Secret Storage Options

​Environment Variables

​Secret References

​File-based Secrets

​Secret Providers

​Local Secret Store

​External Secret Managers

​AWS Secrets Manager

​HashiCorp Vault

​Azure Key Vault

​Secret Syntax

​Basic Secret Reference

​Provider-specific References

​Secret with Default Values

​Complex Secret Structures

​Security Best Practices

​Access Control

​Storage Security

​Network Security

​Rotation and Lifecycle

​Environment-Specific Secrets

​Development Environment

​Production Environment

​Secret Templates

​Database Connection Template

​API Client Template

​Secret Validation

​Required Secrets

​Secret Encryption

​Advanced Features

​Secret Injection at Runtime

​Secret Monitoring

​Multi-Region Secrets

​Troubleshooting

​Common Issues

​Secret Not Found

​Permission Denied

​Secret Decryption Failed

​Debugging Secrets

​Integration Examples

​Complete API Service Configuration

​Multi-Environment Secret Management

​Next Steps

Secrets

What are Secrets?

Secret Storage Options

Environment Variables

Secret References

File-based Secrets

Secret Providers

Local Secret Store

External Secret Managers

AWS Secrets Manager

HashiCorp Vault

Azure Key Vault

Secret Syntax

Basic Secret Reference

Provider-specific References

Secret with Default Values

Complex Secret Structures

Security Best Practices

Access Control

Storage Security

Network Security

Rotation and Lifecycle

Environment-Specific Secrets

Development Environment

Production Environment

Secret Templates

Database Connection Template

API Client Template

Secret Validation

Required Secrets

Secret Encryption

Advanced Features

Secret Injection at Runtime

Secret Monitoring

Multi-Region Secrets

Troubleshooting

Common Issues

Secret Not Found

Permission Denied

Secret Decryption Failed

Debugging Secrets

Integration Examples

Complete API Service Configuration

Multi-Environment Secret Management

Next Steps