Introduction

Introduction to Fizzy MCP

Fizzy MCP is a Model Context Protocol (MCP) server that enables AI assistants to interact with Fizzy, the AI-powered task management platform built for modern teams.

What is MCP?

The Model Context Protocol is an open standard developed by Anthropic that allows AI applications to securely connect to external data sources and tools. It provides a standardized way for AI assistants to:

Access data from external systems
Execute actions through well-defined tools
Maintain context across conversations

Why Fizzy MCP?

Fizzy MCP bridges the gap between your AI assistant and your task management workflow:

Natural Language Control

Manage tasks using conversational commands instead of clicking through UIs.

Context Awareness

Your AI understands your boards, cards, and team structure.

Automation Ready

Chain multiple operations together for complex workflows.

Secure by Design

Uses Personal Access Tokens with configurable permissions.

Deployment Modes

Fizzy MCP offers two deployment modes to fit different use cases:

Remote Mode (Recommended)
Local Mode

Use our hosted MCP service running on Cloudflare Workers. Your AI agent connects via HTTP to https://fizzy-mcp-hosted.ryanyogan.workers.dev/mcp.

Advantages:

No local server to run or maintain
Works with any MCP client that supports HTTP transport
Automatic updates - always running the latest version
Perfect for remote development environments

Considerations:

Rate limits apply (100 writes/day anonymous, 1,000/day with API key)
Requires internet connection
Your Fizzy token is sent to the hosted service

// Example Claude Desktop config (Remote Mode)
{
  "mcpServers": {
    "fizzy": {
      "transport": "http",
      "url": "https://fizzy-mcp-hosted.ryanyogan.workers.dev/mcp",
      "headers": {
        "X-Fizzy-Token": "your-fizzy-token"
      }
    }
  }
}

Run the MCP server locally on your machine. Your AI agent connects via stdio (standard input/output).

Advantages:

No rate limits
Works offline (once authenticated)
Token stays on your machine
Full control over the server

Considerations:

Requires Node.js 20+
Server must be installed and available
May need manual updates

// Example Claude Desktop config (Local Mode)
{
  "mcpServers": {
    "fizzy": {
      "command": "npx",
      "args": ["-y", "fizzy-do-mcp@latest"]
    }
  }
}

Features

40 MCP Tools

Fizzy MCP provides comprehensive API coverage across 7 categories:

Category	Tools	Description
Identity	2	Account discovery and settings
Boards	7	Board CRUD and publishing
Cards	18	Card lifecycle, assignments, tags
Comments	5	Discussion threads on cards
Columns	5	Workflow stage management
Tags	1	Label management
Users	2	Team member information

Auto-Configuration

After authentication, the CLI can automatically detect and configure:

Claude Desktop - Anthropic’s official desktop app
Cursor - AI-powered code editor
OpenCode - Open-source AI coding assistant

The CLI generates the correct configuration for your chosen mode (remote or local) and writes it directly to the agent’s config file.

CLI Commands

Fizzy MCP includes a full-featured CLI for setup and management:

Command	Description
`fizzy-mcp auth`	Configure authentication (mode, token, API key)
`fizzy-mcp configure`	Auto-configure AI agents
`fizzy-mcp whoami`	Show current identity and account
`fizzy-mcp status`	Check configuration status
`fizzy-mcp logout`	Clear stored credentials

Type-Safe Client

Built with TypeScript and Zod validation:

import { FizzyClient } from '@fizzy-mcp/client';

const client = new FizzyClient({
  accessToken: 'your-token',
  accountSlug: '/your-org',
});

// Fully typed responses
const result = await client.cards.list({ board_ids: ['abc123'] });
if (result.ok) {
  console.log(`Found ${result.value.length} cards`);
}

Resilient API Calls

Automatic retry logic with exponential backoff:

Retries on network errors and 5xx responses
Respects rate limit headers
Configurable retry count and delays

How It Works

Remote Mode Flow

┌─────────────────┐
│   You (Human)   │
│                 │
│  "Create a new  │
│   card called   │
│   Fix login"    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   AI Assistant  │
│ (Claude, etc.)  │
│                 │
│  Understands    │
│  your request   │
└────────┬────────┘
         │
         ▼ MCP over HTTP
┌─────────────────┐
│  Fizzy MCP      │
│  Hosted Service │
│                 │
│  Cloudflare     │
│  Workers        │
└────────┬────────┘
         │
         ▼ HTTPS
┌─────────────────┐
│   Fizzy API     │
│                 │
│  Creates card   │
│  Returns data   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   AI Assistant  │
│                 │
│  "Created card  │
│   #42: Fix      │
│   login bug"    │
└─────────────────┘

Local Mode Flow

┌─────────────────┐
│   You (Human)   │
│                 │
│  "Create a new  │
│   card called   │
│   Fix login"    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   AI Assistant  │
│ (Claude, etc.)  │
│                 │
│  Understands    │
│  your request   │
└────────┬────────┘
         │
         ▼ MCP via stdio
┌─────────────────┐
│   Fizzy MCP     │
│   Local Server  │
│                 │
│  fizzy_create_  │
│  card tool      │
└────────┬────────┘
         │
         ▼ HTTPS
┌─────────────────┐
│   Fizzy API     │
│                 │
│  Creates card   │
│  Returns data   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   AI Assistant  │
│                 │
│  "Created card  │
│   #42: Fix      │
│   login bug"    │
└─────────────────┘

Prerequisites

Before getting started, you’ll need:

A Fizzy account - Sign up at app.fizzy.do
Node.js 20+ - Required for the CLI and local mode
An MCP-compatible AI agent - Claude Desktop, Cursor, or OpenCode

Next Steps

Ready to get started? Head to the Installation guide to set up Fizzy MCP.