MCP Endpoint

The MCP (Model Context Protocol) endpoint is the primary interface for AI agents to interact with Fizzy. It implements the MCP Streamable HTTP transport specification, enabling AI assistants like Claude, GPT-4, and custom agents to manage tasks in Fizzy.

Overview

40 Tools

Full access to all Fizzy operations: boards, cards, comments, columns, tags, and users.

Streamable HTTP

Supports both request/response and Server-Sent Events (SSE) for real-time updates.

JSON-RPC 2.0

Standard JSON-RPC protocol for reliable, typed communication.

Authenticated

Secure access via Fizzy Personal Access Tokens.

Endpoints

Method	Endpoint	Description
`POST`	`/mcp`	MCP Streamable HTTP endpoint
`GET`	`/mcp/info`	Server capabilities and tool list

POST /mcp Auth Required

The main MCP endpoint for sending JSON-RPC requests. Supports both synchronous responses and SSE streaming.

Request Headers

Header	Required	Description
`Content-Type`	Yes	Must be `application/json`
`Accept`	Yes	`application/json` or `text/event-stream`
`X-Fizzy-Token`	Yes	Your Fizzy Personal Access Token
`X-Fizzy-Account-Slug`	No	Target account (e.g., `/my-org`)
`X-API-Key`	No	Alternative API key authentication

Request Body

Standard JSON-RPC 2.0 request format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fizzy_list_boards",
    "arguments": {}
  }
}

Response

JSON-RPC 2.0 response:

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

Streaming Response (SSE)

When Accept: text/event-stream is specified, the response is sent as Server-Sent Events:

HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

data: {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"..."}]}}

MCP Protocol Flow

Initialize

Send an initialize request to establish the session and receive server capabilities.
List Tools

Send tools/list to discover available tools and their schemas.
Call Tools

Use tools/call with the tool name and arguments to perform operations.
Handle Responses

Process the JSON-RPC response containing the tool result or error.

Initialize Request

Before using tools, initialize the MCP session:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Fizzy-Token: fz_xxxxxxxxxxxxx" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "my-ai-agent",
        "version": "1.0.0"
      }
    }
  }' \
  https://fizzy-mcp-hosted.ryanyogan.workers.dev/mcp

const TOKEN = 'fz_xxxxxxxxxxxxx';
const MCP_URL = 'https://fizzy-mcp-hosted.ryanyogan.workers.dev/mcp';

async function initialize() {
const response = await fetch(MCP_URL, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-Fizzy-Token': TOKEN
},
body: JSON.stringify({
jsonrpc: '2.0',
id: 1,
method: 'initialize',
params: {
protocolVersion: '2024-11-05',
capabilities: {},
clientInfo: {
name: 'my-ai-agent',
version: '1.0.0'
}
}
})
});

return response.json();
}

const result = await initialize();
console.log('Server Info:', result.result.serverInfo);
console.log('Capabilities:', result.result.capabilities);

import requests

TOKEN = 'fz_xxxxxxxxxxxxx'
MCP_URL = 'https://fizzy-mcp-hosted.ryanyogan.workers.dev/mcp'

def initialize():
    response = requests.post(
        MCP_URL,
        headers={
            'Content-Type': 'application/json',
            'Accept': 'application/json',
            'X-Fizzy-Token': TOKEN
        },
        json={
            'jsonrpc': '2.0',
            'id': 1,
            'method': 'initialize',
            'params': {
                'protocolVersion': '2024-11-05',
                'capabilities': {},
                'clientInfo': {
                    'name': 'my-ai-agent',
                    'version': '1.0.0'
                }
            }
        }
    )
    return response.json()

result = initialize()
print('Server Info:', result['result']['serverInfo'])
print('Capabilities:', result['result']['capabilities'])

Initialize Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "serverInfo": {
      "name": "fizzy-mcp",
      "version": "0.1.0"
    },
    "capabilities": {
      "tools": {
        "listChanged": false
      }
    }
  }
}

List Tools

Discover available tools and their input schemas:

curl
JavaScript

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

async function listTools() {
  const response = await fetch(MCP_URL, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Accept': 'application/json',
      'X-Fizzy-Token': TOKEN
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: 2,
      method: 'tools/list'
    })
  });

  const { result } = await response.json();

  console.log(`Found ${result.tools.length} tools:\n`);
  result.tools.forEach(tool => {
    console.log(`- ${tool.name}: ${tool.description}`);
  });

  return result.tools;
}

Tools List Response

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "fizzy_get_identity",
        "description": "Get the current user identity and list of accessible Fizzy accounts.",
        "inputSchema": {
          "type": "object",
          "properties": {},
          "required": []
        }
      },
      {
        "name": "fizzy_list_boards",
        "description": "List all Fizzy boards you have access to in the current account.",
        "inputSchema": {
          "type": "object",
          "properties": {},
          "required": []
        }
      },
      {
        "name": "fizzy_create_card",
        "description": "Create a new Fizzy card on a board.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "board_id": {
              "type": "string",
              "description": "The board ID to create the card on"
            },
            "title": {
              "type": "string",
              "description": "The card title",
              "minLength": 1
            },
            "description": {
              "type": "string",
              "description": "Card description (supports markdown)"
            }
          },
          "required": ["board_id", "title"]
        }
      }
    ]
  }
}

Call Tools

Execute MCP tools to interact with Fizzy:

Example: List Boards

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

async function callTool(name, args = {}) {
  const response = await fetch(MCP_URL, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Accept': 'application/json',
      'X-Fizzy-Token': TOKEN
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: Date.now(),
      method: 'tools/call',
      params: {
        name,
        arguments: args
      }
    })
  });

  const { result, error } = await response.json();

  if (error) {
    throw new Error(`MCP Error: ${error.message}`);
  }

  // Parse the text content
  const textContent = result.content.find(c => c.type === 'text');
  return JSON.parse(textContent.text);
}

// List all boards
const boards = await callTool('fizzy_list_boards');
console.log('Boards:', boards);

import json

def call_tool(name, args=None):
    response = requests.post(
        MCP_URL,
        headers={
            'Content-Type': 'application/json',
            'Accept': 'application/json',
            'X-Fizzy-Token': TOKEN
        },
        json={
            'jsonrpc': '2.0',
            'id': 1,
            'method': 'tools/call',
            'params': {
                'name': name,
                'arguments': args or {}
            }
        }
    )

    data = response.json()

    if 'error' in data:
        raise Exception(f"MCP Error: {data['error']['message']}")

    # Parse text content
    text_content = next(
        c for c in data['result']['content']
        if c['type'] == 'text'
    )
    return json.loads(text_content['text'])

# List all boards
boards = call_tool('fizzy_list_boards')
print('Boards:', boards)

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Fizzy-Token: fz_xxxxxxxxxxxxx" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "fizzy_create_card",
      "arguments": {
        "board_id": "brd_abc123",
        "title": "Implement user authentication",
        "description": "Add OAuth2 login with Google and GitHub providers.\n\n## Requirements\n- Social login buttons\n- Session management\n- Token refresh"
      }
    }
  }' \
  https://fizzy-mcp-hosted.ryanyogan.workers.dev/mcp

// Create a new card
const card = await callTool('fizzy_create_card', {
  board_id: 'brd_abc123',
  title: 'Implement user authentication',
  description: `Add OAuth2 login with Google and GitHub providers.

## Requirements

- Social login buttons
- Session management
- Token refresh`
  });

console.log(`Created card #${card.number}: ${card.title}`);

Tool Response Format

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"id\":\"crd_xyz789\",\"number\":42,\"title\":\"Implement user authentication\",\"status\":\"published\"}"
      }
    ]
  }
}

GET /mcp/info Public

Returns MCP server capabilities and available tools without authentication.

Request

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

Response

{
  "name": "fizzy-mcp",
  "version": "0.1.0",
  "protocolVersion": "2024-11-05",
  "transport": "streamable-http",
  "capabilities": {
    "tools": {
      "listChanged": false
    }
  },
  "toolCount": 40,
  "toolCategories": {
    "identity": 2,
    "boards": 7,
    "cards": 18,
    "comments": 5,
    "columns": 5,
    "tags": 1,
    "users": 2
  },
  "tools": [
    {
      "name": "fizzy_get_identity",
      "description": "Get the current user identity and list of accessible Fizzy accounts.",
      "category": "identity"
    },
    {
      "name": "fizzy_get_account",
      "description": "Get the current Fizzy account settings.",
      "category": "identity"
    }
  ],
  "documentation": "https://fizzy.yogan.dev",
  "endpoints": {
    "mcp": "POST /mcp",
    "info": "GET /mcp/info"
  }
}

Error Handling

MCP errors are returned as JSON-RPC error responses:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32600,
    "message": "Invalid Request",
    "data": {
      "details": "Missing required parameter: board_id"
    }
  }
}

Error Codes

Code	Name	Description
`-32700`	Parse Error	Invalid JSON
`-32600`	Invalid Request	Invalid JSON-RPC request
`-32601`	Method Not Found	Unknown method
`-32602`	Invalid Params	Invalid method parameters
`-32603`	Internal Error	Server error

Tool Errors

When a tool fails, it returns an error in the result content:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Error: Card not found\nCode: NOT_FOUND_ERROR"
      }
    ],
    "isError": true
  }
}

Streaming with SSE

For long-running operations or real-time updates, use SSE:

curl
JavaScript

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "X-Fizzy-Token: fz_xxxxxxxxxxxxx" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "fizzy_list_cards",
      "arguments": {"board_ids": ["brd_abc123"]}
    }
  }' \
  https://fizzy-mcp-hosted.ryanyogan.workers.dev/mcp

async function callToolWithStreaming(name, args = {}) {
  const response = await fetch(MCP_URL, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Accept': 'text/event-stream',
      'X-Fizzy-Token': TOKEN
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: Date.now(),
      method: 'tools/call',
      params: { name, arguments: args }
    })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const chunk = decoder.decode(value);
    const lines = chunk.split('\n');

    for (const line of lines) {
      if (line.startsWith('data: ')) {
        const data = JSON.parse(line.slice(6));
        console.log('Received:', data);
      }
    }
  }
}

Complete Example

Here’s a complete example that initializes, lists boards, and creates a card:

const TOKEN = 'fz_xxxxxxxxxxxxx';
const MCP_URL = 'https://fizzy-mcp-hosted.ryanyogan.workers.dev/mcp';

async function mcpRequest(method, params = {}) {
  const response = await fetch(MCP_URL, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Accept: 'application/json',
      'X-Fizzy-Token': TOKEN,
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: Date.now(),
      method,
      params,
    }),
  });

  const data = await response.json();
  if (data.error) throw new Error(data.error.message);
  return data.result;
}

async function callTool(name, args = {}) {
  const result = await mcpRequest('tools/call', { name, arguments: args });
  const text = result.content.find((c) => c.type === 'text')?.text;
  return text ? JSON.parse(text) : null;
}

// Main workflow
async function main() {
  // 1. Initialize
  console.log('Initializing MCP session...');
  const init = await mcpRequest('initialize', {
    protocolVersion: '2024-11-05',
    capabilities: {},
    clientInfo: { name: 'my-agent', version: '1.0.0' },
  });
  console.log(`Connected to ${init.serverInfo.name} v${init.serverInfo.version}\n`);

  // 2. Get identity
  const identity = await callTool('fizzy_get_identity');
  console.log(`Logged in as: ${identity.user.name}`);
  console.log(`Accounts: ${identity.accounts.map((a) => a.name).join(', ')}\n`);

  // 3. List boards
  const boards = await callTool('fizzy_list_boards');
  console.log('Boards:');
  boards.forEach((b) => console.log(`  - ${b.name} (${b.cardCount} cards)`));

  // 4. Create a card on the first board
  if (boards.length > 0) {
    const card = await callTool('fizzy_create_card', {
      board_id: boards[0].id,
      title: 'Task from AI Agent',
      description: 'This card was created via the MCP endpoint.',
    });
    console.log(`\nCreated card #${card.number}: ${card.title}`);
  }
}

main().catch(console.error);

Integration with AI Assistants

Claude Desktop

Add to your Claude Desktop config:

{
  "mcpServers": {
    "fizzy": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropic-ai/mcp-remote",
        "https://fizzy-mcp-hosted.ryanyogan.workers.dev/mcp"
      ],
      "env": {
        "X-Fizzy-Token": "fz_xxxxxxxxxxxxx"
      }
    }
  }
}

Custom Agents

Use the MCP SDK for your language:

npm install @modelcontextprotocol/sdk

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport(
  new URL('https://fizzy-mcp-hosted.ryanyogan.workers.dev/mcp'),
  {
    requestInit: {
      headers: {
        'X-Fizzy-Token': 'fz_xxxxxxxxxxxxx',
      },
    },
  },
);

const client = new Client({ name: 'my-agent', version: '1.0.0' });
await client.connect(transport);

const tools = await client.listTools();
console.log(
  'Available tools:',
  tools.tools.map((t) => t.name),
);

Next Steps

Tools Overview - Complete reference of all 40 tools
REST API Overview - Additional REST endpoints
Error Handling - Handle errors gracefully