Quick Start

This guide gets you from zero to managing Fizzy tasks with your AI assistant in under 5 minutes.

Prerequisites

Node.js 20 or higher
A Fizzy account with a Personal Access Token
An MCP-compatible AI agent (Claude Desktop, Cursor, or OpenCode)

Choose Your Mode

Fizzy MCP supports two deployment modes:

Remote Mode (Recommended)

Zero maintenance. Uses our hosted service with HTTP transport. No local server process to manage. - Automatic updates - No Node.js process running - Rate limits apply (upgradeable with API key)

Local Mode

Full control. Traditional stdio MCP server running locally via npx. - No rate limits - Works offline - Requires Node.js runtime

Quick Start (Remote Mode)

Install and Authenticate
Terminal window
```
npx @fizzy-mcp/server auth
```
When prompted for deployment mode, select remote (or just press Enter for the default).
Get Your Access Token

At the token prompt, press Enter to open your browser to the Fizzy API settings page:
```
Enter your access token (or press Enter to open browser):
Opening browser to https://app.fizzy.do/my/profile/api...
```
Copy your token and paste it back in the terminal.
Optional: Add an API Key

For higher rate limits (1,000 writes/day vs 100), enter an API key when prompted:
```
Enter API key (or press Enter to skip): fmcp_xxxxxxxxxxxxx
```

Auto-Configure Your AI Agent

When prompted, confirm to configure your AI agents:

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

Restart Your AI Agent

Close and reopen your AI agent (Claude Desktop, Cursor, etc.) to load the new MCP server.
Start Using Fizzy!

Try these commands with your AI:

“Show me my Fizzy boards”

“Create a card on the Engineering board called ‘Fix login bug’”

“What cards are assigned to me?”

Quick Start (Local Mode)

Install and Authenticate
Terminal window
```
npx @fizzy-mcp/server auth --mode local
```
Get Your Access Token

Press Enter to open your browser, or paste your token directly:
```
Enter your access token (or press Enter to open browser): fz_xxxxxxxxxxxxx
```

Auto-Configure Your AI Agent

Confirm to configure your agents for local mode:

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

Configuring for local mode...

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

Restart Your AI Agent

Close and reopen your AI agent to load the MCP server.
Start Using Fizzy!

Try these commands with your AI:

“Show me my Fizzy boards”

“Create a card on the Engineering board called ‘Fix login bug‘“

CLI Options Reference

The auth command supports several options for non-interactive setup:

# Default: interactive remote mode
npx @fizzy-mcp/server auth

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

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

# Skip agent configuration
npx @fizzy-mcp/server auth --no-configure

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

Example Conversations

Viewing Boards

You: “What boards do I have access to?”

Claude: I’ll check your Fizzy boards.

[
  { "id": "abc123", "name": "Engineering", "cards_count": 24 },
  { "id": "def456", "name": "Design", "cards_count": 12 },
  { "id": "ghi789", "name": "Marketing", "cards_count": 8 }
]

You have access to 3 boards: Engineering (24 cards), Design (12 cards), and Marketing (8 cards).

Creating Cards

You: “Create a high-priority card for ‘Implement OAuth login’ on the Engineering board”

Claude: I’ll create that card for you.

Created card #142: “Implement OAuth login” on the Engineering board.

Managing Workflow

You: “Move card #142 to the ‘In Progress’ column”

Claude: Done! Card #142 has been moved to the “In Progress” column.

Working with Tags

You: “Tag card #142 with ‘urgent’ and ‘backend’”

Claude: I’ve added both tags to card #142:

#urgent
#backend

Assigning Cards

You: “Assign card #142 to Sarah”

Claude: Card #142 has been assigned to Sarah.

Manual Configuration

If auto-configuration doesn’t work, you can manually add Fizzy MCP to your agent’s config file.

Remote Mode Configuration

Edit ~/.config/Claude/claude_desktop_config.json (Linux/macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "fizzy": {
      "type": "http",
      "url": "https://fizzy-mcp-hosted.ryanyogan.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer fz_xxxxxxxxxxxxx",
        "X-Fizzy-Api-Key": "fmcp_xxxxxxxxxxxxx"
      }
    }
  }
}

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "fizzy": {
      "type": "http",
      "url": "https://fizzy-mcp-hosted.ryanyogan.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer fz_xxxxxxxxxxxxx",
        "X-Fizzy-Api-Key": "fmcp_xxxxxxxxxxxxx"
      }
    }
  }
}

Edit ~/.config/opencode/opencode.json:

{
  "mcp": {
    "fizzy": {
      "type": "http",
      "url": "https://fizzy-mcp-hosted.ryanyogan.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer fz_xxxxxxxxxxxxx",
        "X-Fizzy-Api-Key": "fmcp_xxxxxxxxxxxxx"
      }
    }
  }
}

Edit ~/.claude/settings.json:

{
  "mcpServers": {
    "fizzy": {
      "type": "http",
      "url": "https://fizzy-mcp-hosted.ryanyogan.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer fz_xxxxxxxxxxxxx",
        "X-Fizzy-Api-Key": "fmcp_xxxxxxxxxxxxx"
      }
    }
  }
}

Local Mode Configuration

Edit ~/.config/Claude/claude_desktop_config.json (Linux/macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "fizzy": {
      "command": "npx",
      "args": ["@fizzy-mcp/server"]
    }
  }
}

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "fizzy": {
      "command": "npx",
      "args": ["@fizzy-mcp/server"]
    }
  }
}

Edit ~/.config/opencode/opencode.json:

{
  "mcp": {
    "fizzy": {
      "type": "local",
      "command": "npx",
      "args": ["@fizzy-mcp/server"]
    }
  }
}

Edit ~/.claude/settings.json:

{
  "mcpServers": {
    "fizzy": {
      "command": "npx",
      "args": ["@fizzy-mcp/server"]
    }
  }
}

Configuration with Environment Variables

For both modes, you can use environment variables instead of storing tokens in config files:

Remote Mode
Local Mode

{
  "mcpServers": {
    "fizzy": {
      "type": "http",
      "url": "https://fizzy-mcp-hosted.ryanyogan.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${FIZZY_ACCESS_TOKEN}",
        "X-Fizzy-Api-Key": "${FIZZY_API_KEY}"
      }
    }
  }
}

Then set environment variables:

export FIZZY_ACCESS_TOKEN=fz_xxxxxxxxxxxxx
export FIZZY_API_KEY=fmcp_xxxxxxxxxxxxx  # Optional

{
  "mcpServers": {
    "fizzy": {
      "command": "npx",
      "args": ["@fizzy-mcp/server"],
      "env": {
        "FIZZY_ACCESS_TOKEN": "${FIZZY_ACCESS_TOKEN}"
      }
    }
  }
}

Then set environment variables:

export FIZZY_ACCESS_TOKEN=fz_xxxxxxxxxxxxx

Rate Limits

Tier	Write Operations	Read Operations
Anonymous (no API key)	100/day	Unlimited
With API Key	1,000/day	Unlimited

Write operations include: creating cards, updating cards, deleting cards, moving cards, adding comments, etc.

To check your current usage or upgrade your rate limit:

Go to app.fizzy.do/my/profile/api
Create or view your API key
Re-run npx @fizzy-mcp/server auth to add the key

Troubleshooting

”fizzy” tools not appearing

Verify authentication: npx @fizzy-mcp/server whoami
Check the config was added to your agent’s config file
Restart your AI agent completely (not just refresh)
For remote mode, verify the endpoint is accessible:
Terminal window
```
curl https://fizzy-mcp-hosted.ryanyogan.workers.dev/health
```

“Not authenticated” errors

Run npx @fizzy-mcp/server auth again to re-authenticate.

”Rate limit exceeded” (Remote Mode)

Add an API key: npx @fizzy-mcp/server auth --api-key fmcp_xxxxxxxxxxxxx
Wait for the daily reset
Switch to local mode: npx @fizzy-mcp/server auth --mode local

Slow responses (Local Mode)

The first call may take a few seconds as the server starts. Subsequent calls are faster.

Connection errors (Remote Mode)

Check your internet connection

Verify the hosted service is running:

curl https://fizzy-mcp-hosted.ryanyogan.workers.dev/health

Try local mode as a fallback

Token vs API Key Confusion

Access Token (fz_): Required for all modes. Authenticates you with Fizzy.
API Key (fmcp_): Optional, remote mode only. Increases rate limits.

Next Steps

Tools Reference - Explore all 40+ available tools
Working with Boards - Learn board management
Managing Cards - Master card workflows
Authentication Details - Deep dive into auth options