Floyd MCP Server

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

For the engine's API documentation, see the docs folder in the engine repo.

Tools

Tool	Description
floyd_get_available_slots	Check available appointment times for a service
floyd_hold_booking	Place a temporary hold on a time slot
floyd_confirm_booking	Confirm a held booking (requires explicit user consent)
floyd_cancel_booking	Cancel a held or confirmed booking
floyd_reschedule_booking	Move a booking to a new time
floyd_update_booking	Update a booking's metadata
floyd_get_booking	Retrieve booking details and status

Setup

pnpm install

Environment variables

Variable	Required	Default	Description
FLOYD_BASE_URL	No	http://localhost:4000/v1	Floyd Engine base URL
PORT	No	3000	HTTP 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
                                   ↘ reschedule_booking
                                   ↘ update_booking (metadata)

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
5. Reschedule — move a booking to a new time, preserving its identity
6. Update — attach or replace metadata (e.g. party size, special requests)

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.