# Environment Management Guide

Managing staging and production environments with the MCP Gateway CLI.

## 📋 Table of Contents

- [Quick Start](#quick-start)
- [Method 1: Profiles (Recommended)](#method-1-profiles-recommended)
- [Method 2: Environment Variables](#method-2-environment-variables)
- [Method 3: Shell Aliases](#method-3-shell-aliases)
- [Best Practices](#best-practices)
- [Config File Structure](#config-file-structure)

---

## Quick Start

**TL;DR:** CLI points to production by default. Create profiles for other environments:

```bash
# Production (default) - works immediately
mcpgw auth login
mcpgw workspace list

# For staging/local, create profiles
mcpgw profile create staging --api-url https://staging-api.mcpgw.io/api/v1
mcpgw profile create local --api-url http://localhost:8000/api/v1

# Switch between environments
mcpgw profile use staging
mcpgw auth login
mcpgw workspace list

mcpgw profile use production  # Back to production
```

---

## Method 1: Profiles (Recommended)

**Best for:** Teams, multiple environments, switching contexts frequently

### Setup Profiles

```bash
# Production is the default - no profile needed
# Just use: mcpgw auth login

# Create staging profile for testing
mcpgw profile create staging --api-url https://staging-api.mcpgw.io/api/v1

# Create local dev profile for development
mcpgw profile create local --api-url http://localhost:8000/api/v1
```

### List Profiles

```bash
mcpgw profile list
```

Output:
```
📋 Configuration Profiles:

  → staging
     API: https://staging-api.mcpgw.io/api/v1
     Auth: ✅ Logged in

    production
     API: https://api.mcpgw.io/api/v1
     Auth: ✅ Logged in

    local
     API: http://localhost:8000/api/v1
     Auth: ❌ Not logged in
```

### Switch Profiles

```bash
# Switch to production
mcpgw profile use production

# All subsequent commands use production
mcpgw workspace list
mcpgw backend add ...
```

### Check Current Profile

```bash
mcpgw profile current
```

Output:
```
→ Current profile: production
  API URL: https://api.mcpgw.io/api/v1
  Auth: ✅ Logged in
```

### Delete Profile

```bash
mcpgw profile delete staging
```

### Per-Command Profile Override

```bash
# Use staging for just this command
MCPGW_PROFILE=staging mcpgw workspace list

# Or with --profile flag (if added)
mcpgw --profile staging workspace list
```

---

## Method 2: Environment Variables

**Best for:** CI/CD pipelines, scripts, temporary overrides

### Available Variables

- `MCPGW_API_URL` - API endpoint (e.g., `https://api.mcpgw.io/api/v1`)
- `MCPGW_PROFILE` - Profile name to use
- `MCPGW_TOKEN` - Authentication token (for CI/CD)
- `MCPGW_WORKSPACE` - Default workspace ID

### Usage Examples

```bash
# Point to staging
export MCPGW_API_URL=https://staging-api.mcpgw.io/api/v1
mcpgw workspace list

# Point to production
export MCPGW_API_URL=https://api.mcpgw.io/api/v1
mcpgw workspace list

# One-liner for single command
MCPGW_API_URL=https://staging-api.mcpgw.io/api/v1 mcpgw workspace list
```

### CI/CD Example (GitHub Actions)

```yaml
name: Deploy to Staging
on:
  push:
    branches: [develop]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Install CLI
        run: pip install mcpgw
      
      - name: Deploy Backend
        env:
          MCPGW_API_URL: https://staging-api.mcpgw.io/api/v1
          MCPGW_TOKEN: ${{ secrets.STAGING_TOKEN }}
          MCPGW_WORKSPACE: ${{ secrets.STAGING_WORKSPACE_ID }}
        run: |
          mcpgw backend add --name "New Service" --url "http://service:9000"
```

---

## Method 3: Shell Aliases

**Best for:** Quick commands, personal productivity, keyboard warriors

### Add to `~/.zshrc` or `~/.bashrc`

```bash
# Staging aliases
alias mcpgw-staging='MCPGW_API_URL=https://staging-api.mcpgw.io/api/v1 mcpgw'
alias mg-staging='MCPGW_API_URL=https://staging-api.mcpgw.io/api/v1 mcpgw'
alias mgs='MCPGW_API_URL=https://staging-api.mcpgw.io/api/v1 mcpgw'

# Production aliases
alias mcpgw-prod='MCPGW_API_URL=https://api.mcpgw.io/api/v1 mcpgw'
alias mg-prod='MCPGW_API_URL=https://api.mcpgw.io/api/v1 mcpgw'
alias mgp='MCPGW_API_URL=https://api.mcpgw.io/api/v1 mcpgw'

# Local dev alias
alias mcpgw-local='MCPGW_API_URL=http://localhost:8000/api/v1 mcpgw'
alias mg-local='MCPGW_API_URL=http://localhost:8000/api/v1 mcpgw'
alias mgl='MCPGW_API_URL=http://localhost:8000/api/v1 mcpgw'
```

### Reload Shell

```bash
source ~/.zshrc  # or ~/.bashrc
```

### Usage

```bash
# Use staging
mgs workspace list
mgs backend add ...

# Use production
mgp workspace list
mgp backend add ...

# Use local
mgl workspace list
```

---

## Best Practices

### 1. **Don't Mix Staging and Production**

❌ Bad:
```bash
# Logged into production but pointing at staging
mcpgw profile use production
MCPGW_API_URL=https://staging-api.mcpgw.io/api/v1 mcpgw workspace list
```

✅ Good:
```bash
# Use profiles correctly
mcpgw profile use staging
mcpgw workspace list
```

### 2. **Separate Credentials**

Each profile stores its own authentication token:

```bash
# Login to staging
mcpgw profile use staging
mcpgw auth login  # Uses staging credentials

# Login to production
mcpgw profile use production
mcpgw auth login  # Uses production credentials
```

### 3. **Use Descriptive Profile Names**

```bash
# Good profile names
mcpgw profile create staging
mcpgw profile create production
mcpgw profile create local-dev
mcpgw profile create demo-environment

# Avoid generic names
mcpgw profile create test  # Which test env?
mcpgw profile create env1  # What is env1?
```

### 4. **Document Your Environments**

Create a `.mcpgw-environments` file in your project:

```bash
# .mcpgw-environments
# MCP Gateway Environment Configuration

# Local Development
# mcpgw profile create local --api-url http://localhost:8000/api/v1

# Staging
# mcpgw profile create staging --api-url https://staging-api.mcpgw.io/api/v1
# UI: https://staging.mcpgw.io

# Production
# mcpgw profile create production --api-url https://api.mcpgw.io/api/v1
# UI: https://mcpgw.io
```

### 5. **CI/CD: Use Tokens, Not Passwords**

```bash
# Generate a token in the UI
# Then in CI/CD:
export MCPGW_TOKEN="eyJhbGc..."
export MCPGW_API_URL="https://api.mcpgw.io/api/v1"

# No need to login
mcpgw workspace list  # Uses token automatically
```

### 6. **Verify Your Environment**

Always check before critical operations:

```bash
# Check current profile
mcpgw profile current

# Check workspace
mcpgw workspace current

# Verify API endpoint
echo $MCPGW_API_URL
```

---

## Config File Structure

Location: `~/.mcpgw/config.json`

```json
{
  "current_profile": "production",
  "profiles": {
    "staging": {
      "api_url": "https://staging-api.mcpgw.io/api/v1",
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "workspace_id": "123e4567-e89b-12d3-a456-426614174000"
    },
    "production": {
      "api_url": "https://api.mcpgw.io/api/v1",
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "workspace_id": "987fcdeb-51a2-43f1-9876-543210fedcba"
    },
    "local": {
      "api_url": "http://localhost:8000/api/v1",
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  }
}
```

### Direct File Editing (Advanced)

You can manually edit `~/.mcpgw/config.json`, but it's safer to use CLI commands.

---

## Comparison: Profiles vs Environment Variables

| Feature | Profiles | Environment Variables |
|---------|----------|----------------------|
| **Setup Complexity** | One-time `profile create` | Export each time |
| **Context Switching** | `profile use staging` | `export MCPGW_API_URL=...` |
| **Credential Storage** | Per-profile (secure) | Must manage separately |
| **CI/CD Friendly** | ✅ Yes (`MCPGW_PROFILE=staging`) | ✅ Yes (direct vars) |
| **Multiple Workspaces** | ✅ Stored per profile | ❌ Single workspace |
| **Team Sharing** | ✅ Documented commands | ⚠️ Need to share URLs |
| **Quick One-offs** | ⚠️ Need to switch | ✅ Inline override |

**Recommendation:** Use **profiles** for your primary workflow, **environment variables** for CI/CD and scripts.

---

## Examples

### Example 1: Test in Staging, Deploy to Production

```bash
# Test in staging
mcpgw profile use staging
mcpgw backend add --name "Gmail MCP" --url "http://gmail-mcp:9000"
mcpgw workspace list  # Verify it works

# Deploy to production
mcpgw profile use production
mcpgw backend add --name "Gmail MCP" --url "http://gmail-mcp:9000"
mcpgw workspace list  # Verify it works
```

### Example 2: CI/CD Pipeline

```bash
#!/bin/bash
# deploy.sh

# Set environment
export MCPGW_API_URL="https://api.mcpgw.io/api/v1"
export MCPGW_TOKEN="${PROD_TOKEN}"  # From secrets
export MCPGW_WORKSPACE="${PROD_WORKSPACE_ID}"

# Deploy
mcpgw backend add \
  --name "New Service" \
  --url "http://service:9000" \
  --auth-mode oauth

echo "✅ Deployed to production"
```

### Example 3: Multiple Developers

Developer A:
```bash
mcpgw profile create my-staging --api-url https://staging-api.mcpgw.io/api/v1
mcpgw profile use my-staging
mcpgw auth login --email alice@example.com
```

Developer B:
```bash
mcpgw profile create my-staging --api-url https://staging-api.mcpgw.io/api/v1
mcpgw profile use my-staging
mcpgw auth login --email bob@example.com
```

Both can work on staging with their own credentials.

---

## Troubleshooting

### "Not authenticated" error after switching profiles

**Cause:** Each profile stores its own token.

**Solution:** Login to the new profile:
```bash
mcpgw profile use staging
mcpgw auth login
```

### Commands going to wrong environment

**Check:**
1. Current profile: `mcpgw profile current`
2. Environment variables: `echo $MCPGW_API_URL`
3. Active workspace: `mcpgw workspace current`

**Fix:** Switch profile or unset environment variables:
```bash
mcpgw profile use production
unset MCPGW_API_URL  # Clear env var
```

### Profile not found

**List available profiles:**
```bash
mcpgw profile list
```

**Create the profile:**
```bash
mcpgw profile create staging --api-url https://staging-api.mcpgw.io/api/v1
```

---

## Summary

**For most users:** Use **profiles** (`mcpgw profile create/use`)
- Clean separation of environments
- Stores credentials per environment
- Easy context switching

**For CI/CD:** Use **environment variables**
- `MCPGW_API_URL`, `MCPGW_TOKEN`, `MCPGW_WORKSPACE`
- No config file needed
- Works with secrets management

**For power users:** Add **shell aliases**
- Lightning-fast switching
- Customize to your workflow
- Combine with profiles for best UX

**You don't need separate CLIs for staging/prod** - one CLI with profiles is cleaner, easier to maintain, and provides better UX.
