Claude Desktop

Claude Desktop Configuration

This guide covers setting up Fizzy MCP with Claude Desktop, Anthropic’s official desktop application.

Deployment Modes

Fizzy MCP supports two deployment modes:

Mode	Description	Best For
Remote (Recommended)	Connects to hosted Fizzy MCP service via HTTP	Most users, zero maintenance, always up-to-date
Local	Runs MCP server locally via npx	Offline use, custom modifications, self-hosting

Auto-Configuration

The easiest way to configure Claude Desktop is through the Fizzy MCP CLI:

npx fizzy-do-mcp auth

Or use the configure command directly:

npx fizzy-do-mcp configure

When prompted, select Claude Desktop for automatic configuration. The CLI will detect the best mode for your setup.

Configuration File Location

~/Library/Application Support/Claude/claude_desktop_config.json

%APPDATA%\Claude\claude_desktop_config.json

~/.config/Claude/claude_desktop_config.json

Manual Configuration

Choose your deployment mode and add the configuration to your Claude Desktop config file:

Remote Mode (Recommended)
Local Mode

Remote mode connects to the hosted Fizzy MCP service via HTTP transport.

Basic Remote Configuration

{
  "mcpServers": {
    "fizzy": {
      "transport": "http",
      "url": "https://fizzy-mcp-hosted.ryanyogan.workers.dev/mcp",
      "headers": {
        "X-Fizzy-Token": "your-fizzy-token"
      }
    }
  }
}

Remote Configuration with All Headers

{
  "mcpServers": {
    "fizzy": {
      "transport": "http",
      "url": "https://fizzy-mcp-hosted.ryanyogan.workers.dev/mcp",
      "headers": {
        "X-Fizzy-Token": "your-fizzy-token",
        "X-Fizzy-Account-Slug": "/my-org",
        "X-API-Key": "fmcp_your_api_key"
      }
    }
  }
}

Local mode runs the MCP server on your machine via stdio.

Basic Local Configuration

{
  "mcpServers": {
    "fizzy": {
      "command": "npx",
      "args": ["-y", "fizzy-do-mcp@latest"]
    }
  }
}

Local Configuration with Environment Variables

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

After adding the configuration, completely close and reopen Claude Desktop to load the new settings.

Remote Mode Headers

When using remote mode, the following headers are available:

Header	Required	Description
`X-Fizzy-Token`	Yes	Your Fizzy personal access token (from app.fizzy.do)
`X-Fizzy-Account-Slug`	No	Account slug like `/my-org` to select a specific account
`X-API-Key`	No	API key for higher rate limits (prefix: `fmcp_`)

Getting an API Key

API keys provide higher rate limits for power users. To obtain one:

Contact Fizzy support or visit the API dashboard
API keys are prefixed with fmcp_ (e.g., fmcp_abc123xyz...)
Add the key to your configuration’s X-API-Key header

Verifying the Connection

After restarting Claude Desktop:

Start a new conversation
Look for the MCP tools icon (usually a wrench or plugin icon)
You should see “fizzy” listed as a connected server

Try asking Claude:

“What Fizzy boards do I have access to?”

Configuration Options

Using a Global Installation (Local Mode Only)

If you installed Fizzy MCP globally:

{
  "mcpServers": {
    "fizzy": {
      "command": "fizzy-mcp"
    }
  }
}

Authentication for Local Mode

When using local mode, authenticate with Fizzy:

npx fizzy-do-mcp auth

This stores your credentials securely in ~/.config/fizzy-mcp/config.json (mode 0600). No need to put tokens in your MCP config unless you prefer explicit configuration.

Multiple MCP Servers

You can run Fizzy alongside other MCP servers:

Mixed Remote/Local
All Local

{
  "mcpServers": {
    "fizzy": {
      "transport": "http",
      "url": "https://fizzy-mcp-hosted.ryanyogan.workers.dev/mcp",
      "headers": {
        "X-Fizzy-Token": "your-fizzy-token"
      }
    },
    "github": {
      "command": "npx",
      "args": ["@github/mcp-server"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem"]
    }
  }
}

{
  "mcpServers": {
    "fizzy": {
      "command": "npx",
      "args": ["-y", "fizzy-do-mcp@latest"]
    },
    "github": {
      "command": "npx",
      "args": ["@github/mcp-server"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem"]
    }
  }
}

Troubleshooting

Tools not appearing

Check that the config file is valid JSON
Verify the file is in the correct location
Ensure you’ve restarted Claude Desktop completely
Check Claude Desktop logs for MCP connection errors

”Not authenticated” errors (Remote Mode)

Verify your X-Fizzy-Token header is correct:

Check that the token is valid at app.fizzy.do
Ensure there are no extra spaces or quotes around the token
Regenerate the token if needed

”Not authenticated” errors (Local Mode)

Run fizzy-mcp auth to set up or refresh your credentials:

npx fizzy-do-mcp auth

Connection timeouts (Remote Mode)

Check your internet connection
Verify the hosted service is accessible: curl https://fizzy-mcp-hosted.ryanyogan.workers.dev/health
If using a corporate network, check for firewall rules blocking the connection

Connection timeouts (Local Mode)

Check your internet connection
Verify Fizzy API is accessible: curl https://app.fizzy.do/api/health
Try increasing the timeout in Claude Desktop settings

Server crashes (Local Mode)

Check the server logs. You can run the server manually to see errors:

npx fizzy-do-mcp

Best Practices

Use remote mode for automatic updates and zero maintenance
Keep tokens secure - never commit them to version control
Use X-Fizzy-Account-Slug if you have access to multiple accounts
Restart Claude Desktop after any configuration changes
Check fizzy-mcp status if you encounter authentication issues (local mode)