Hosted Service

Fizzy MCP Hosted Service

The Fizzy MCP Hosted Service provides remote MCP access without requiring you to run a local server. Your AI assistant connects directly to our cloud infrastructure, giving you instant access to all Fizzy MCP tools from anywhere.

What is the Hosted Service?

The hosted service is a fully managed MCP server running on Cloudflare’s global edge network. Instead of running npx @fizzy-mcp/server locally, your AI agent connects via HTTP to our hosted endpoint:

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

This endpoint speaks the Model Context Protocol over HTTP Streamable transport, making it compatible with any MCP client that supports HTTP-based connections.

Why Use the Hosted Service?

No Local Server

Skip installation and configuration. Connect directly from your AI agent without running anything locally.

Always Updated

Automatically running the latest version. No manual updates or version management required.

Works Anywhere

Access from any device or environment with an internet connection. Perfect for remote development, cloud IDEs, and mobile workflows.

Zero Maintenance

We handle uptime, scaling, and infrastructure. Focus on using Fizzy, not managing servers.

Architecture

The hosted service is built on a modern, globally distributed architecture designed for reliability and low latency:

┌─────────────────────────────────────────────────────────────────┐
│                     Your AI Assistant                          │
│                  (Claude, Cursor, OpenCode)                    │
└─────────────────────────┬───────────────────────────────────────┘
                          │
                          │ MCP over HTTP
                          │ (Streamable Transport)
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                 Cloudflare Workers Edge                         │
│                                                                 │
│  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐      │
│  │   Worker      │  │   Worker      │  │   Worker      │      │
│  │  (US-West)    │  │  (EU-West)    │  │  (Asia-East)  │      │
│  └───────────────┘  └───────────────┘  └───────────────┘      │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐ │
│  │                    D1 Database                            │ │
│  │          (Rate limits, usage tracking, analytics)         │ │
│  └───────────────────────────────────────────────────────────┘ │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐ │
│  │                    KV Storage                             │ │
│  │              (API keys, session data, caching)            │ │
│  └───────────────────────────────────────────────────────────┘ │
└─────────────────────────┬───────────────────────────────────────┘
                          │
                          │ HTTPS
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Fizzy API                                │
│                    https://app.fizzy.do                         │
└─────────────────────────────────────────────────────────────────┘

Infrastructure Components

Component	Purpose
Cloudflare Workers	Serverless compute at the edge, handling MCP protocol translation
D1 Database	SQLite-compatible database for rate limiting and usage analytics
KV Storage	Key-value store for API key validation and session management
Workers AI	Optional AI features for enhanced tool processing

Base URL and Endpoints

Endpoint	Method	Description
/mcp	POST	Main MCP endpoint for tool calls
/health	GET	Health check endpoint

Base URL

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

Tip

The hosted service runs on Cloudflare’s global network with 300+ edge locations, ensuring low latency regardless of your location.

Authentication

The hosted service requires your Fizzy Personal Access Token to authenticate requests to the Fizzy API. This token is passed via the X-Fizzy-Token HTTP header.

Required Headers

Header	Required	Description
X-Fizzy-Token	Yes	Your Fizzy Personal Access Token (starts with fz_)
X-API-Key	No	Optional API key for higher rate limits (starts with fmcp_)
Content-Type	Yes	Must be application/json

Caution

Your Fizzy token is sent to the hosted service with each request. The service uses it only to authenticate with the Fizzy API on your behalf and does not store it permanently.

How Authentication Works

1. You configure your AI agent with your Fizzy token in the headers

2. Your AI agent sends an MCP request to the hosted service

3. The hosted service validates the request format and checks rate limits

4. The hosted service forwards the request to the Fizzy API using your token

5. The Fizzy API returns the response, which is relayed back to your AI agent

Quick Start

Get up and running with the hosted service in minutes:

1. Get your Fizzy token

   Go to app.fizzy.do, navigate to Profile → API, and create a Personal Access Token.

2. Test the connection

   Use curl to verify your token works:

   curl -X POST https://fizzy-mcp-hosted.ryanyogan.workers.dev/mcp \
     -H "Content-Type: application/json" \
     -H "X-Fizzy-Token: fz_your_token_here" \
     -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/list",
       "params": {}
     }'

   You should receive a JSON response listing all available tools.

3. Configure your AI agent (see examples below)

4. Start using Fizzy

   Open your AI agent and try a command like:

   “List all my Fizzy boards”

Agent Configuration Examples

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

Cursor

Add to your Cursor MCP settings (~/.cursor/mcp.json):

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

OpenCode

Add to your OpenCode config (~/.config/opencode/opencode.json):

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

Example: Calling a Tool

Here’s a complete example of calling the fizzy_list_boards tool via the hosted service:

curl -X POST https://fizzy-mcp-hosted.ryanyogan.workers.dev/mcp \
  -H "Content-Type: application/json" \
  -H "X-Fizzy-Token: fz_your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "fizzy_list_boards",
      "arguments": {}
    }
  }'

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[{\"id\":\"abc123\",\"name\":\"Product Roadmap\",\"card_count\":42}]"
      }
    ]
  }
}

Rate Limits

The hosted service implements rate limiting to ensure fair usage. See the Rate Limits page for detailed information.

Quick overview:

Tier	Writes/Day	Reads/Day
Anonymous	100	1,000
Authenticated (API Key)	1,000	10,000
Admin	Unlimited	Unlimited

Note

Need higher limits? See API Keys to learn how to get an API key for 10x higher rate limits.

Comparison: Hosted vs Local

Feature	Hosted Service	Local Server
Setup	None (just configure headers)	Install Node.js, run npx
Updates	Automatic	Manual (npm update)
Rate Limits	Yes (100-1,000 writes/day)	None
Offline Access	No	Yes (after auth)
Token Storage	Sent with each request	Stored locally
Latency	Network roundtrip	Direct stdio
Best For	Remote dev, cloud IDEs, simplicity	High-volume, offline, privacy

Security Considerations

Token Handling

• Your Fizzy token is transmitted over HTTPS (TLS 1.3)
• The token is used only for the duration of the request
• Tokens are never logged or stored permanently
• Each request is isolated at the edge

Network Security

• All connections use HTTPS with modern cipher suites
• Cloudflare provides DDoS protection and WAF
• Edge locations reduce attack surface
• Request validation prevents injection attacks

Best Practices

Tip

• Rotate your Fizzy token periodically - Use an API key for production workflows - Monitor your usage via rate limit headers - Never commit tokens to version control

Troubleshooting

”401 Unauthorized”

• Verify your X-Fizzy-Token header is set correctly
• Ensure the token starts with fz_
• Check that the token hasn’t been revoked in Fizzy

”429 Too Many Requests”

• You’ve exceeded your rate limit
• Check the X-RateLimit-Reset header for when limits reset
• Consider getting an API key for higher limits

”Connection refused” or timeout

• Verify you have internet connectivity
• Check if Cloudflare is experiencing issues: cloudflarestatus.com
• Ensure your firewall allows HTTPS to *.workers.dev

Next Steps

• Rate Limits - Understand usage limits and tiers
• API Keys - Get higher rate limits
• Tools Reference - Explore all available MCP tools