Authentication

Authentication

Fizzy MCP uses Personal Access Tokens (PATs) to authenticate with the Fizzy API. The CLI provides a streamlined authentication flow that automatically configures your AI agents.

Deployment Modes

Fizzy MCP supports two deployment modes:

Remote Mode (Recommended)

Uses our hosted service for zero-maintenance operation. No local server process required. Endpoint: https://fizzy-mcp-hosted.ryanyogan.workers.dev/mcp

Local Mode

Traditional stdio MCP server running locally via npx. Full control over the server process.

Tip

Remote mode is recommended for most users. It eliminates the need to manage a local server process and provides automatic updates. Local mode is available for users who prefer full control or have specific network requirements.

Getting a Personal Access Token

1. Open Fizzy

   Go to app.fizzy.do and sign in to your account.

2. Navigate to API Settings

   Click your avatar in the top-right corner, then go to Profile → API.

   Or navigate directly to: https://app.fizzy.do/my/profile/api

3. Create a New Token

   Click Create Token and give it a descriptive name (e.g., “Claude Desktop MCP”).

4. Copy the Token

   Copy the generated token. It starts with fz_ and won’t be shown again.

Caution

Store your token securely! It provides full access to your Fizzy account and cannot be retrieved after creation.

Running Authentication

Run the auth command to configure Fizzy MCP:

npx @fizzy-mcp/server auth

CLI Options

The auth command supports the following options:

Option	Description
-m, --mode <mode>	Deployment mode: remote (default) or local
-k, --api-key <key>	API key for higher rate limits (remote mode only)
--no-configure	Skip auto-configuration of AI agents

Examples:

# Interactive auth (recommended)
npx @fizzy-mcp/server auth

# Explicitly use remote mode
npx @fizzy-mcp/server auth --mode remote

# Use local mode
npx @fizzy-mcp/server auth --mode local

# Remote mode with API key for higher rate limits
npx @fizzy-mcp/server auth --mode remote --api-key fmcp_xxxxxxxxxxxxx

# Auth without configuring AI agents
npx @fizzy-mcp/server auth --no-configure

Interactive Auth Flow

Here’s what the full interactive authentication flow looks like:

  _____ _
 |  ___(_)_________   _
 | |_  | |_  /_  / | | |
 |  _| | |/ / / /| |_| |
 |_|   |_/___/___|\__, |
                  |___/
AI-powered task management for the modern team
v0.2.0

┌─ Deployment Mode ─────────────────────────────────────┐
│                                                       │
│ Choose how Fizzy MCP connects to your AI agents:     │
│                                                       │
│ • Remote (recommended) - Uses hosted service          │
│   No local server required, automatic updates         │
│                                                       │
│ • Local - Traditional stdio MCP server                │
│   Runs via npx, full control over the process         │
│                                                       │
└───────────────────────────────────────────────────────┘

Select deployment mode [remote/local]: remote

┌─ Authentication ──────────────────────────────────────┐
│                                                       │
│ To authenticate, you need a Personal Access Token.   │
│                                                       │
│ Press Enter to open the browser, or paste your token. │
│                                                       │
└───────────────────────────────────────────────────────┘

Enter your access token (or press Enter to open browser):

Tip

Quick Tip: Press Enter without typing anything to automatically open your browser to the Fizzy API settings page where you can create or copy a token.

After pressing Enter, your browser opens to https://app.fizzy.do/my/profile/api:

Opening browser to https://app.fizzy.do/my/profile/api...

Enter your access token: ********

After entering your token:

✔ Validated token
✔ Welcome, Ryan Carniato!

Account: ryan

API Key Configuration (Remote Mode)

When using remote mode, you’ll be prompted for an optional API key:

┌─ API Key (Optional) ──────────────────────────────────┐
│                                                       │
│ An API key increases your rate limits:                │
│                                                       │
│ • Anonymous:  100 writes/day                          │
│ • With key:   1,000 writes/day                        │
│                                                       │
│ Get an API key at https://app.fizzy.do/my/profile/api │
│                                                       │
└───────────────────────────────────────────────────────┘

Enter API key (or press Enter to skip): fmcp_xxxxxxxxxxxxx

✔ API key validated

Note

API keys use the prefix fmcp_ (Fizzy MCP) and are different from Personal Access Tokens which use fz_. API keys are only used for rate limiting in remote mode.

Agent Auto-Configuration

After authentication, the CLI detects and configures your AI agents:

┌─ Detected AI Agents ──────────────────────────────────┐
│                                                       │
│ • Claude Desktop                                      │
│ • Cursor                                              │
│ • OpenCode ✓                                          │
│                                                       │
└───────────────────────────────────────────────────────┘

Would you like to configure Fizzy for these agents? [Y/n] y

Configuring for remote mode...

✔ Configured Claude Desktop
  → ~/.config/Claude/claude_desktop_config.json

✔ Configured Cursor
  → ~/.cursor/mcp.json

✔ Configured OpenCode
  → ~/.config/opencode/opencode.json

Done! Restart your AI agents to activate Fizzy MCP.

Rate Limits (Remote Mode)

Remote mode enforces rate limits to ensure fair usage:

Tier	Write Operations	Read Operations
Anonymous	100/day	Unlimited
With API Key	1,000/day	Unlimited

Tip

Write operations include creating, updating, deleting, and moving cards. Read operations (listing boards, viewing cards, etc.) are unlimited.

To upgrade your rate limits, add an API key:

npx @fizzy-mcp/server auth --api-key fmcp_xxxxxxxxxxxxx

Or reconfigure:

npx @fizzy-mcp/server auth --mode remote

Account Selection

If you have access to multiple Fizzy accounts, you’ll be prompted to select one:

Available accounts:
  - Personal (/ryan)
  - Acme Corp (/acme)
  - Side Project (/side-project)

Which account would you like to use?
(Press Enter to auto-detect at runtime, or enter the account slug)
Account slug: /acme

Tip

If you leave this blank, Fizzy MCP will auto-detect the account at runtime, which is useful if you switch between accounts frequently.

Verifying Authentication

Check your authentication status:

npx @fizzy-mcp/server whoami

Output:

Name: Ryan Carniato
Email: ryan@example.com
Avatar: https://...

Mode: remote
Endpoint: https://fizzy-mcp-hosted.ryanyogan.workers.dev/mcp
API Key: fmcp_xxx...xxx (configured)

Accounts:
  - Personal (/ryan) (active)
  - Acme Corp (/acme)

Token Security

Fizzy MCP stores your credentials securely:

• File permissions: Config file is created with mode 600 (owner-only read/write)
• Hidden input: Token is not displayed when typing
• No logging: Tokens are never logged or transmitted except to the Fizzy API
• Secure storage: API keys are stored separately from access tokens

Where Credentials Are Stored

Platform	Location
macOS/Linux	~/.config/fizzy-mcp/config.json
Windows	%USERPROFILE%\.config\fizzy-mcp\config.json

Config File Structure

{
  "mode": "remote",
  "accessToken": "fz_xxxxxxxxxxxxx",
  "apiKey": "fmcp_xxxxxxxxxxxxx",
  "accountSlug": "/ryan"
}

Revoking Tokens

To revoke a token:

1. Go to app.fizzy.do
2. Navigate to Profile → API
3. Find the token and click Revoke

Then clear local credentials:

npx @fizzy-mcp/server logout

Using Environment Variables

For CI/CD or server deployments, use environment variables:

# Required
export FIZZY_ACCESS_TOKEN=fz_xxxxxxxxxxxxx

# Optional
export FIZZY_ACCOUNT_SLUG=/my-org
export FIZZY_MODE=remote
export FIZZY_API_KEY=fmcp_xxxxxxxxxxxxx

These take precedence over the config file.

Environment Variable Reference

Variable	Description	Example
FIZZY_ACCESS_TOKEN	Personal Access Token (required)	fz_xxxxxxxxxxxxx
FIZZY_ACCOUNT_SLUG	Account to use	/my-org
FIZZY_MODE	Deployment mode	remote or local
FIZZY_API_KEY	API key for rate limits (remote only)	fmcp_xxxxxxxxxxxxx

Troubleshooting

”Invalid access token”

• Ensure the token is copied correctly (no extra spaces)
• Check that the token hasn’t been revoked
• Verify you’re using a PAT (prefix fz_), not an API key (prefix fmcp_)

“Invalid API key”

• Ensure the API key starts with fmcp_
• Check that the key hasn’t been revoked
• Note: API keys are only used in remote mode

”Rate limit exceeded”

• Add an API key to increase your limit to 1,000 writes/day
• Wait until the rate limit resets (daily)
• Consider switching to local mode for unlimited writes

”No accessible accounts”

• Your token may not have access to any accounts
• Contact your Fizzy administrator to grant access

”Authentication failed”

• Check your internet connection
• Verify the Fizzy API is accessible: curl https://app.fizzy.do/api/health
• For remote mode, verify the hosted service: curl https://fizzy-mcp-hosted.ryanyogan.workers.dev/health

Browser doesn’t open

If pressing Enter doesn’t open your browser:

1. Manually navigate to https://app.fizzy.do/my/profile/api
2. Copy your token
3. Paste it at the prompt

Next Steps

With authentication complete, proceed to Quick Start to begin using Fizzy MCP.