Floyd

Scheduling and booking engine for AI agents. Check availability, hold slots, and confirm appointments with two-phase booking and conflict-free resource management.

GitHub

Floyd MCP Server

MCP server that exposes Floyd scheduling and booking tools to AI agents. Built on the Model Context Protocol Streamable HTTP transport.

For full API documentation, see docs.floyd.run.

Tools

ToolDescription
floyd_get_available_slotsCheck available appointment times for a service
floyd_hold_bookingPlace a temporary hold on a time slot
floyd_confirm_bookingConfirm a held booking (requires explicit user consent)
floyd_cancel_bookingCancel a held or confirmed booking
floyd_get_bookingRetrieve booking details and status

Setup

pnpm install

Environment variables

VariableRequiredDefaultDescription
FLOYD_BASE_URLNohttps://api.floyd.run/v1Floyd API base URL
PORTNo3000HTTP server port

Usage

HTTP mode (Streamable HTTP)

pnpm dev

MCP endpoint: POST / Health check: GET /health

Stdio mode

pnpm dev -- --stdio

Authentication

When the Floyd engine requires authentication, connecting agents provide their API key via:

  1. Authorization: Bearer <token> header (preferred)
  2. ?token=<value> query parameter

The API key is forwarded to the Floyd engine on each request. If the engine has auth disabled (e.g. self-hosted), no key is needed.

Booking flow

get_available_slots → hold_booking → confirm_booking
                                   ↘ cancel_booking
  1. Get slots — query available times, returns signed slotId tokens
  2. Hold — reserve a slot using the slotId (or explicit fields). Creates a booking in held state
  3. Confirm — finalize the booking. Requires userConfirmed: true
  4. Cancel — release a held or confirmed booking

Development

pnpm test          # run tests
pnpm typecheck     # type-check
pnpm lint          # eslint
pnpm format        # prettier
pnpm build         # bundle with tsup

Production

pnpm build
pnpm start

The server handles SIGTERM/SIGINT for graceful shutdown. HTTP requests to the Floyd API have a 10-second timeout.

Related Servers