Environment Variables

Fizzy MCP can be configured using environment variables, which take precedence over the config file. Environment variables are particularly useful for CI/CD pipelines, Docker containers, and managing multiple configurations.

Available Variables

Core Variables

Variable	Required	Description	Default
`FIZZY_ACCESS_TOKEN`	Yes*	Personal Access Token	From config file
`FIZZY_ACCOUNT_SLUG`	No	Account slug (e.g., `/my-org`)	Auto-detect
`FIZZY_BASE_URL`	No	API base URL	`https://app.fizzy.do`

Remote Mode Variables

Variable	Required	Description	Default
`FIZZY_MCP_MODE`	No	Deployment mode: `remote` or `local`	`local`
`FIZZY_MCP_URL`	No	Custom hosted MCP URL (for self-hosting)	`https://fizzy-mcp-hosted.ryanyogan.workers.dev/mcp`
`FIZZY_MCP_API_KEY`	No	API key for hosted service (prefix: `fmcp_`)	None

Variable Details

FIZZY_MCP_MODE

Controls whether the MCP server runs locally or connects to the hosted service.

Value	Description
`remote`	Connect to hosted Fizzy MCP service (recommended)
`local`	Run MCP server locally (default)

# Use hosted service
export FIZZY_MCP_MODE=remote

# Use local server (default)
export FIZZY_MCP_MODE=local

FIZZY_MCP_API_KEY

API key for the hosted service. Provides higher rate limits for power users.

Prefix: fmcp_
Example: fmcp_abc123xyz789...

export FIZZY_MCP_API_KEY=fmcp_your_api_key_here

FIZZY_MCP_URL

Custom URL for the hosted MCP service. Only needed if you’re self-hosting Fizzy MCP or using a custom deployment.

# Default hosted service
export FIZZY_MCP_URL=https://fizzy-mcp-hosted.ryanyogan.workers.dev/mcp

# Self-hosted instance
export FIZZY_MCP_URL=https://fizzy-mcp.mycompany.com/mcp

FIZZY_ACCESS_TOKEN

Your Fizzy personal access token. Get this from app.fizzy.do under Settings > Personal Access Tokens.

export FIZZY_ACCESS_TOKEN=fz_xxxxxxxxxxxxx

FIZZY_ACCOUNT_SLUG

Specify which Fizzy account to use if you have access to multiple accounts.

export FIZZY_ACCOUNT_SLUG=/my-org

FIZZY_BASE_URL

Custom Fizzy API base URL. Only needed for enterprise deployments with a custom Fizzy instance.

export FIZZY_BASE_URL=https://fizzy.mycompany.com

Usage Examples

Shell Export

# Remote mode configuration
export FIZZY_MCP_MODE=remote
export FIZZY_ACCESS_TOKEN=fz_xxxxxxxxxxxxx
export FIZZY_ACCOUNT_SLUG=/my-org
export FIZZY_MCP_API_KEY=fmcp_your_api_key

# Local mode configuration
export FIZZY_MCP_MODE=local
export FIZZY_ACCESS_TOKEN=fz_xxxxxxxxxxxxx
export FIZZY_ACCOUNT_SLUG=/my-org

In AI Agent Config (Local Mode)

Most MCP clients support an env field for local mode servers:

Claude Desktop / Cursor
OpenCode

{
  "mcpServers": {
    "fizzy": {
      "command": "npx",
      "args": ["-y", "fizzy-do-mcp@latest"],
      "env": {
        "FIZZY_ACCESS_TOKEN": "fz_xxxxxxxxxxxxx",
        "FIZZY_ACCOUNT_SLUG": "/my-org",
        "FIZZY_MCP_MODE": "local"
      }
    }
  }
}

{
  "mcp": {
    "fizzy": {
      "type": "local",
      "command": ["npx", "-y", "fizzy-do-mcp@latest"],
      "env": {
        "FIZZY_ACCESS_TOKEN": "fz_xxxxxxxxxxxxx",
        "FIZZY_ACCOUNT_SLUG": "/my-org"
      }
    }
  }
}

dotenv Files

For local development, you can use a .env file in your project:

# Mode selection
FIZZY_MCP_MODE=remote

# Authentication
FIZZY_ACCESS_TOKEN=fz_xxxxxxxxxxxxx
FIZZY_ACCOUNT_SLUG=/my-org

# Remote mode settings
FIZZY_MCP_API_KEY=fmcp_your_api_key
FIZZY_MCP_URL=https://fizzy-mcp-hosted.ryanyogan.workers.dev/mcp

# Custom Fizzy instance (enterprise)
# FIZZY_BASE_URL=https://fizzy.mycompany.com

Precedence Order

Configuration is resolved in this order (highest priority first):

Environment variables (highest priority)
HTTP headers (for remote mode agent configs)
Config file (~/.config/fizzy-mcp/config.json)
Default values (lowest priority)

Example Precedence

If you have:

FIZZY_ACCOUNT_SLUG=/env-org in environment
account_slug: "/config-org" in config file
X-Fizzy-Account-Slug: /header-org in agent headers

The environment variable wins: /env-org will be used.

CI/CD Usage

For automated deployments, set environment variables in your CI system:

- name: Run with Fizzy (Remote)
  env:
    FIZZY_MCP_MODE: remote
    FIZZY_ACCESS_TOKEN: ${{ secrets.FIZZY_TOKEN }}
    FIZZY_ACCOUNT_SLUG: /my-org
    FIZZY_MCP_API_KEY: ${{ secrets.FIZZY_MCP_API_KEY }}
  run: |
    npx fizzy-do-mcp status

- name: Run with Fizzy (Local)
  env:
    FIZZY_MCP_MODE: local
    FIZZY_ACCESS_TOKEN: ${{ secrets.FIZZY_TOKEN }}
    FIZZY_ACCOUNT_SLUG: /my-org
  run: |
    npx fizzy-do-mcp status

GitLab CI

variables:
  FIZZY_MCP_MODE: remote
  FIZZY_ACCOUNT_SLUG: /my-org

script:
  - npx fizzy-do-mcp status

Use GitLab CI/CD variables for secrets:

FIZZY_ACCESS_TOKEN
FIZZY_MCP_API_KEY

Docker

Dockerfile

FIZZY_MCP_MODE=remote ENV FIZZY_ACCOUNT_SLUG=/my-org # Pass secrets at runtime instead ```
</TabItem>
<TabItem label="Runtime">
```bash # Recommended: pass secrets at runtime docker run \ -e FIZZY_MCP_MODE=remote \ -e
FIZZY_ACCESS_TOKEN=fz_xxx \ -e FIZZY_MCP_API_KEY=fmcp_xxx \ -e FIZZY_ACCOUNT_SLUG=/my-org \
my-app ```
</TabItem>
<TabItem label="Docker Compose">
```yaml services: app: image: my-app environment: FIZZY_MCP_MODE: remote FIZZY_ACCOUNT_SLUG:
/my-org FIZZY_ACCESS_TOKEN: ${FIZZY_ACCESS_TOKEN}
FIZZY_MCP_API_KEY: ${FIZZY_MCP_API_KEY}

Self-Hosting Configuration

For organizations running their own Fizzy MCP hosted service:

# Point to your self-hosted instance
export FIZZY_MCP_URL=https://fizzy-mcp.internal.mycompany.com/mcp
export FIZZY_MCP_MODE=remote
export FIZZY_ACCESS_TOKEN=fz_xxxxxxxxxxxxx

# If also running a custom Fizzy instance
export FIZZY_BASE_URL=https://fizzy.internal.mycompany.com

Security Considerations

Never log or print access tokens - they provide full access to your Fizzy account
Use secrets management in CI/CD - never hardcode tokens in pipeline files
Rotate tokens regularly - especially for production/CI environments
Prefer config file auth for local development - it’s more secure than environment variables
Keep API keys confidential - they may provide higher rate limits
Use separate tokens for CI/CD - easier to revoke if compromised

Recommended Security Practices

For local development: Use fizzy-mcp auth to store credentials securely
For CI/CD: Use your platform’s secrets management (GitHub Secrets, GitLab CI Variables, etc.)
For Docker: Pass secrets at runtime, never bake them into images
For teams: Consider using API keys with rate limiting for shared environments

Debugging Environment Variables

To see which configuration values are being used:

npx fizzy-do-mcp status

This will show:

Current mode (remote/local)
Authentication status
Active account
API endpoint being used