README.md
Scheduling and booking engine for AI agents.
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
| 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 | https://api.floyd.run/v1 |
Floyd API 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:
Authorization: Bearer <token>header (preferred)?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)
- Get slots — query available times, returns signed
slotIdtokens - Hold — reserve a slot using the
slotId(or explicit fields). Creates a booking inheldstate - Confirm — finalize the booking. Requires
userConfirmed: true - Cancel — release a held or confirmed booking
- Reschedule — move a booking to a new time, preserving its identity
- 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.
Tools (7)
floyd_get_available_slotsCheck available appointment times for a servicefloyd_hold_bookingPlace a temporary hold on a time slotfloyd_confirm_bookingConfirm a held booking (requires explicit user consent)floyd_cancel_bookingCancel a held or confirmed bookingfloyd_reschedule_bookingMove a booking to a new timefloyd_update_bookingUpdate a booking's metadatafloyd_get_bookingRetrieve booking details and statusEnvironment Variables
FLOYD_BASE_URLFloyd API base URLPORTHTTP server portConfiguration
claude_desktop_config.json
{"mcpServers": {"floyd": {"command": "npx", "args": ["-y", "@floyd-run/mcp-server"], "env": {"FLOYD_BASE_URL": "https://api.floyd.run/v1"}}}}Try it
→Check available slots for a consultation next Tuesday.
→Hold a booking for the 2 PM slot and confirm it.
→Reschedule my existing booking to tomorrow at 10 AM.
→Update my booking metadata to include a party size of 4.