SECRETS_USAGE_EXAMPLES.md

HAL Secrets Usage Examples

This document provides practical examples of using HAL's secret management feature.

Setup

First, configure your secrets in the environment. For Claude Desktop, add them to your configuration:

{
  "mcpServers": {
    "hal": {
      "command": "npx",
      "args": ["hal-mcp"],
      "env": {
        "HAL_SECRET_GITHUB_TOKEN": "ghp_your_actual_token_here",
        "HAL_SECRET_API_KEY": "your_api_key_here",
        "HAL_SECRET_USERNAME": "your_username",
        "HAL_SECRET_PASSWORD": "your_password"
      }
    }
  }
}

Discovering Available Secrets

Before using secrets, you can check what secret keys are available using the list-secrets tool:

Tool call:

{}

Response:

Available secrets (4 total):

You can use these secret keys in your HTTP requests using the {secrets.key} syntax:

1. {secrets.github_token}
2. {secrets.api_key}
3. {secrets.username}
4. {secrets.password}

Usage examples:
- URL: "https://api.example.com/data?token={secrets.github_token}"
- Header: {"Authorization": "Bearer {secrets.github_token}"}
- Body: {"username": "{secrets.username}"}

This tool only shows the key names - the actual secret values are never exposed to the AI.

Example Use Cases

1. GitHub API with Personal Access Token

Tool call:

{
  "url": "https://api.github.com/user/repos",
  "headers": {
    "Authorization": "Bearer {secrets.github_token}",
    "Accept": "application/vnd.github.v3+json"
  }
}

What happens:

• AI sees: "Authorization": "Bearer {secrets.github_token}"
• HAL sends: "Authorization": "Bearer ghp_your_actual_token_here"

2. Authentication with API Key in Query Parameter

Tool call:

{
  "url": "https://api.example.com/data?api_key={secrets.api_key}&limit=10"
}

What happens:

• AI sees: https://api.example.com/data?api_key={secrets.api_key}&limit=10
• HAL sends: https://api.example.com/data?api_key=your_api_key_here&limit=10

3. Login with Username and Password

Tool call:

{
  "url": "https://api.example.com/auth/login",
  "body": "{\"username\": \"{secrets.username}\", \"password\": \"{secrets.password}\"}",
  "headers": {
    "Content-Type": "application/json"
  }
}

What happens:

• AI sees: {"username": "{secrets.username}", "password": "{secrets.password}"}
• HAL sends: {"username": "your_username", "password": "your_password"}

4. Custom Headers with Multiple Secrets

Tool call:

{
  "url": "https://api.service.com/endpoint",
  "headers": {
    "X-API-Key": "{secrets.api_key}",
    "X-Client-ID": "{secrets.client_id}",
    "Authorization": "Bearer {secrets.access_token}"
  }
}

5. OAuth 2.0 Token Exchange

Tool call:

{
  "url": "https://oauth2.googleapis.com/token",
  "body": "grant_type=client_credentials&client_id={secrets.client_id}&client_secret={secrets.client_secret}",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  }
}

6. Database Connection String (for API endpoints that accept connection strings)

Tool call:

{
  "url": "https://api.example.com/query",
  "body": "{\"connection\": \"postgresql://user:{secrets.database_password}@localhost:5432/mydb\", \"query\": \"SELECT * FROM users\"}",
  "headers": {
    "Content-Type": "application/json"
  }
}

Security Benefits

1. AI Never Sees Secrets: The AI only sees template placeholders like {secrets.api_key}, never the actual values.

2. Environment-Based Configuration: Secrets are managed through environment variables, following security best practices.

3. No Secret Leakage: Even if conversation logs are stored, they only contain placeholders, not actual secrets.

4. Flexible Key Naming: Environment variables use the HAL_SECRET_ prefix, and keys are case-insensitive in templates.

Best Practices

1. Use Descriptive Names:

   • ✅ HAL_SECRET_GITHUB_TOKEN
   • ❌ HAL_SECRET_T1

2. Scope Secrets Appropriately:

   • Use separate tokens for different services
   • Don't reuse the same secret for multiple purposes

3. Regular Rotation:

   • Rotate secrets regularly
   • Update environment variables when secrets change

4. Least Privilege:

   • Use API keys with minimal required permissions
   • Create service-specific tokens when possible

Troubleshooting

If a secret substitution fails, you'll see a warning like:

Warning: Secret 'api_key' not found. Available secrets: github_token, username, password

Common issues:

1. Case mismatch: HAL_SECRET_API_KEY → use {secrets.api_key} (lowercase)
2. Missing prefix: Environment variable must start with HAL_SECRET_
3. Typo in template: Make sure you use {secrets.key} format exactly

Advanced Usage with Swagger/OpenAPI

When using HAL with Swagger/OpenAPI integration, secrets work seamlessly with auto-generated tools:

{
  "id": "user123",
  "headers": {
    "Authorization": "Bearer {secrets.api_key}"
  }
}

The secrets will be substituted before making the request to any Swagger-generated endpoint.