OnceHub MCP Server

The OnceHub MCP Server provides a standardized way for AI models and agents to interact directly with your OnceHub scheduling API. Rather than sending users a booking link and asking them to schedule manually, an AI Agent can retrieve availability and schedule meetings on the user’s behalf using MCP tools, through a natural language flow. This solution enables external AI Agents to access OnceHub scheduling APIs within AI-driven workflows using the standardized Model Context Protocol (MCP) remote server.

Compatible with: VS Code Copilot, Claude Desktop, OpenAI, and any MCP-compatible AI client.

Table of Contents

• Features
• Quick Start
• Architecture
• Tools
• Client Configuration
• Installation
• Testing
• Production Deployment
• Contributing
• License

Features

• 🔌 MCP Protocol Support - Works with any MCP-compatible AI client
• 📅 Time Slot Retrieval - Fetch available booking slots from OnceHub booking calendars
• 🗓️ Meeting Scheduling - Automatically schedule meetings with guest information
• 🔐 Secure Authentication - API key-based authentication via headers
• 🧪 Well Tested - 92% code coverage with comprehensive unit tests
• 🐳 Docker Ready - Containerized for easy deployment
• 📝 AI-Friendly Prompts - Built-in workflow guidance for AI assistants

Quick Start

Get started with the OnceHub MCP Server in your AI client:

1. Get Your API Key

Obtain your OnceHub API key from the Authentication documentation.

2. Configure Your Client

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "oncehub": {
      "url": "https://mcp.oncehub.com/sse",
      "type": "http",
      "headers": {
        "authorization": "Bearer YOUR_ONCEHUB_API_KEY"
      }
    }
  }
}

Replace YOUR_ONCEHUB_API_KEY with your actual API key.

3. Start Using

Ask your AI assistant to:

• "Show me available time slots for calendar BKC-XXXXXXXXXX"
• "Schedule a meeting for tomorrow at 2 PM with John Doe"

⚠️ Running your own MCP server? See Installation & Running Locally for setup instructions.

✅ Production Server: Our hosted MCP server is available at https://mcp.oncehub.com/sse.

Architecture

Project Structure

mcp-server/
├── main.py              # MCP server with tool definitions
├── models.py            # Pydantic data schemas for BookingForm and Location
├── pyproject.toml       # Project dependencies and configuration
├── Dockerfile           # Docker image configuration
├── .dockerignore        # Files to exclude from Docker build
└── README.md            # This file

Tools

1. get_booking_time_slots

Retrieves available time slots from a booking calendar.

Parameters:

• calendar_id (str, required): The booking calendar ID (e.g., 'BKC-XXXXXXXXXX')
• start_time (str, optional): Filter slots from this datetime in ISO 8601 format (e.g., '2026-02-15T09:00:00Z')
• end_time (str, optional): Filter slots until this datetime in ISO 8601 format (e.g., '2026-02-28T17:00:00Z')
• timeout (int, default: 30): Request timeout in seconds

Example Response:

{
  "success": true,
  "status_code": 200,
  "calendar_id": "BKC-XXXXXXXXXX",
  "total_slots": 5,
  "data": [
    {"start_time": "2026-02-10T10:00:00Z", "end_time": "2026-02-10T11:00:00Z"},
    {"start_time": "2026-02-10T14:00:00Z", "end_time": "2026-02-10T15:00:00Z"}
  ]
}

2. schedule_meeting

Schedules a meeting in a specified time slot. Always call get_booking_time_slots first to ensure the time slot is available.

Parameters:

• calendar_id (str, required): ID of the booking calendar (e.g., 'BKC-XXXXXXXXXX')
• start_time (str, required): The exact start time from an available slot in ISO 8601 format
• guest_time_zone (str, required): Guest's timezone in IANA format (e.g., 'America/New_York', 'Europe/London')
• guest_name (str, required): Guest's full name
• guest_email (str, required): Guest's email address for confirmation
• guest_phone (str, optional): Guest's phone number in E.164 format (e.g., '+15551234567')
• location_type (str, optional): Meeting mode - 'virtual', 'virtual_static', 'physical', or 'guest_phone'
• location_value (str, optional): Location details based on type:
  • virtual: Provider name (e.g., 'zoom', 'google_meet', 'microsoft_teams')
  • virtual_static: Use null
  • physical: Address ID (e.g., 'ADD-XXXXXXXXXX')
  • guest_phone: Phone number in E.164 format
• custom_fields (dict, optional): Custom form fields as key-value pairs (e.g., {"company": "Acme", "interests": ["Demo"]})
• timeout (int, default: 30): Request timeout in seconds

Example Response:

{
  "success": true,
  "status_code": 200,
  "booking_id": "BKG-123456789",
  "confirmation": {
    "guest_name": "John Doe",
    "guest_email": "john@example.com",
    "scheduled_time": "2026-02-10T10:00:00Z",
    "timezone": "America/New_York"
  }
}

Prerequisites

• Python 3.13 or higher
• uv package manager (recommended)
• OnceHub API key - See Authentication documentation to obtain your API key
• OnceHub API endpoint URL (usually https://api.oncehub.com)

Environment Variables

Create a .env file or set these environment variables:

# Required: Your OnceHub API endpoint
ONCEHUB_API_URL=https://api.oncehub.com

# Note: API key is passed via Authorization header from MCP clients
# Do NOT commit API keys to version control

Client Configuration

This MCP server is compatible with VS Code Copilot, Claude Desktop, OpenAI, and other MCP-compatible clients.

VS Code / GitHub Copilot

Step 1: Create Configuration Directory

Windows (PowerShell):

New-Item -Path ".vscode" -ItemType Directory -Force
New-Item -Path ".vscode\mcp.json" -ItemType File -Force

macOS/Linux:

mkdir -p .vscode
touch .vscode/mcp.json

Step 2: Configure the Server

Edit .vscode/mcp.json:

{
  "servers": {
    "oncehub": {
      "url": "http://0.0.0.0:8000/sse",
      "type": "http",
      "headers": {
        "authorization": "Bearer YOUR_ONCEHUB_API_KEY"
      }
    }
  }
}

Configuration Options:

• url: The MCP server endpoint (change to your server URL if self-hosting)
• authorization: Your OnceHub API key with Bearer prefix
• Server name (oncehub): Can be customized to any identifier

Step 3: Reload VS Code

After saving the configuration, reload VS Code to activate the MCP server connection.

Claude Desktop

Edit your Claude Desktop configuration file:

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

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "oncehub": {
      "url": "http://0.0.0.0:8000/sse",
      "headers": {
        "authorization": "Bearer YOUR_ONCEHUB_API_KEY"
      }
    }
  }
}

Restart Claude Desktop after saving.

Other MCP Clients

For other MCP-compatible clients, configure them to connect to:

• Endpoint: http://0.0.0.0:8000/sse
• Protocol: HTTP with Server-Sent Events (SSE)
• Authentication: Bearer token in Authorization header

Security Note: Never commit API keys to version control. Use environment variables or secure secret management for production deployments.