OpenCode

OpenCode Configuration

This guide covers setting up Fizzy MCP with OpenCode, the open-source AI coding assistant.

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 OpenCode 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 OpenCode for automatic configuration. The CLI will handle the format differences automatically.

Configuration File Location

OpenCode configuration is at:

~/.config/opencode/opencode.json

Manual Configuration

Choose your deployment mode. Note that OpenCode uses type instead of transport:

Remote Mode (Recommended)
Local Mode

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

Basic Remote Configuration

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

Remote Configuration with All Headers

{
  "mcp": {
    "fizzy": {
      "type": "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.

Basic Local Configuration

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

Local Configuration with Environment Variables

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

After adding the configuration, reload or restart OpenCode to apply the changes.

OpenCode-Specific Format

Key Differences

Feature	OpenCode	Claude Desktop / Cursor
Config key	`mcp`	`mcpServers`
Remote type field	`"type": "http"`	`"transport": "http"`
Local type field	`"type": "local"`	Not used
Command format	Array: `["npx", "-y", "pkg"]`	String + args: `"command": "npx"` + `"args": ["-y", "pkg"]`

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

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

OpenCode (Local)
Claude/Cursor (Local)

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

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

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_`)

Verifying the Connection

After configuration:

Start OpenCode
Check the MCP status indicator
Test with: “List my Fizzy boards”

Authentication for Local Mode

After configuring OpenCode with 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.

Configuration Options

With Global Install (Local Mode Only)

{
  "mcp": {
    "fizzy": {
      "type": "local",
      "command": ["fizzy-mcp"]
    }
  }
}

Multiple MCP Servers

You can run Fizzy alongside other MCP servers:

Mixed Remote/Local
All Local

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

{
  "mcp": {
    "fizzy": {
      "type": "local",
      "command": ["npx", "-y", "fizzy-do-mcp@latest"]
    },
    "github": {
      "type": "local",
      "command": ["npx", "@github/mcp-server"]
    }
  }
}

Troubleshooting

Server not connecting

Verify the config file location (~/.config/opencode/opencode.json)
Check that you’re using type not transport
For local mode, ensure type: "local" is present
For remote mode, ensure type: "http" is present
Test server manually (local mode): npx fizzy-do-mcp status

”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

Invalid configuration format

OpenCode requires specific format. Common mistakes:

Using mcpServers instead of mcp
Using transport instead of type
Using separate command and args instead of a single command array

Connection issues (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

Best Practices

Use remote mode for automatic updates and zero maintenance
Double-check the format - OpenCode uses different syntax than other agents
Keep tokens secure - never commit config files with tokens to version control
Use X-Fizzy-Account-Slug if you have access to multiple Fizzy accounts
Use the CLI for auto-configuration to avoid format mistakes