OnceHub

- 🔌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

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

Create.vscode/mcp.jsonin your workspace:

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

ReplaceYOUR_ONCEHUB_API_KEYwith your actual API key.

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

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

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

Retrieves available time slots from a booking calendar.

- 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

Create a.envfile 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

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

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

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

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

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

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" } } } }

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 inAuthorizationheader

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

Installation & Running Locally with uv

1. Install uv (if not already installed)

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

curl -LsSf https://astral.sh/uv/install.sh | sh

git clone https://github.com/scheduleonce/mcp-server.git cd mcp-server

$env:ONCEHUB_API_URL="https://api.oncehub.com"

export ONCEHUB_API_URL="https://api.oncehub.com"

echo "ONCEHUB_API_URL=https://api.oncehub.com" > .env

Note:The API key is passed via theAuthorizationheader from MCP clients (not as an environment variable).

The server will start onhttp://0.0.0.0:8000

docker run -p 8000:8000 \ -e ONCEHUB_API_URL="https://api.oncehub.com" \ mcp-server

version: '3.8' services: mcp-server: build: . ports: - "8000:8000" environment: - ONCEHUB_API_URL=https://api.oncehub.com restart: unless-stopped

- type(str): Location type ("physical", "virtual", "phone")
- value(str): Location details (address, URL, phone number)

The server includes comprehensive logging for HTTP requests to OnceHub:

- Outgoing requests (→)
- Response status codes (←)
- Request/response bodies

Logs are output to the console with timestamps and log levels.

- GET /health- Health check endpoint
- GET /healthy- Alternate health check endpoint
- GET /sse- Server-Sent Events endpoint for MCP protocol communication
- GET /tools- Returns the registered MCP tools with their descriptions, required parameters, and input field details

Editmain.pyand changelog_levelparameter:

asyncio.run(mcp.run_sse_async(host="0.0.0.0", port=8000, log_level="debug"))

Available log levels:"debug","info","warning","error","critical"

The project includes comprehensive unit tests for all tools and functions.

# Install test dependencies uv pip install pytest pytest-asyncio pytest-cov pytest-mock

uv run pytest --cov=. --cov-report=html --cov-report=term

uv run pytest test_tools.py::TestGetBookingTimeSlots

uv run pytest test_tools.py::TestGetBookingTimeSlots::test_get_time_slots_success

After running tests with coverage, open the HTML report:

# Windows start htmlcov/index.html # macOS open htmlcov/index.html # Linux xdg-open htmlcov/index.html

- test_tools.py- Unit tests for all tool functions

- TestGetApiKeyFromContext- Tests for API key extraction
- TestGetBookingTimeSlots- Tests for time slot retrieval
- TestScheduleMeeting- Tests for meeting scheduling

All tests use mocking to avoid actual API calls and ensure fast, reliable test execution.

- Never commit API keys to version control
- Use environment variables or secret management systems
- Rotate API keys regularly

- Use HTTPS in production (add reverse proxy like nginx)
- Implement rate limiting to prevent abuse
- Use firewall rules to restrict access

- Monitor the/healthendpoint for availability
- Set up logging aggregation (e.g., ELK stack, CloudWatch)
- Track API response times and error rates

# Build and tag the image docker build -t oncehub-mcp-server:1.0.0 . # Run with restart policy docker run -d \ --name oncehub-mcp \ --restart unless-stopped \ -p 8000:8000 \ -e ONCEHUB_API_URL="https://api.oncehub.com" \ oncehub-mcp-server:1.0.0

- AWS: Use ECS, Fargate, or EC2 with Application Load Balancer
- Azure: Deploy to Azure Container Instances or App Service
- GCP: Use Cloud Run or Google Kubernetes Engine

- Default timeout is 30 seconds - adjust based on your needs
- The server uses asyncio for concurrent request handling
- Consider horizontal scaling for high-traffic scenarios
- Use connection pooling for database/cache if added

# Simple health check script curl -f http://localhost:8000/health || exit 1 # Docker healthcheck (add to Dockerfile) HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \ CMD curl -f http://localhost:8000/health || exit 1

Ensure you're passing theapi_keyparameter when calling the tools.

Error: "404 Not Found" on/health

Make sure the server is running and accessible on port 8000.

Error: "405 Method Not Allowed" on/sse

The SSE endpoint requires a GET request, not POST. Use proper MCP client libraries or curl with GET.

Check that logging is properly configured inmain.pyand the server is running withlog_level="info"or"debug".