MCP Endpoint

API reference for the FlowCaptain MCP (Model Context Protocol) endpoint for automatic tool discovery.

FlowCaptain provides an MCP (Model Context Protocol) endpoint that lets voice bot platforms and AI agents automatically discover and use all appointment tools.

Endpoint

POST /mcp?calendarId=YOUR_CALENDAR_ID

calendarId is a required query parameter specifying which calendar the tools operate on. Without it, the API returns a 400 error. You can find your calendar ID pre-filled in every example under Calendar › Name › API, section Integration Guide.

Only POST is supported — GET and DELETE requests to /mcp receive a 405 error. The endpoint is stateless: every request stands on its own; there are no MCP sessions.

Headers

Authorization: Bearer sk_live_your_api_key
Accept: application/json, text/event-stream
Content-Type: application/json

The Accept header must include both application/json and text/event-stream. Voice bot platforms like Retell and VAPI send this automatically.

How It Works

MCP is a protocol that enables dynamic discovery of AI tools. Instead of configuring each endpoint manually, your voice bot connects once to the MCP endpoint and automatically sees all available tools:

The platform sends an initialize request to discover capabilities
Then it sends a tools/list request to get all available tools
When the voice bot needs to check availability or book an appointment, it sends a tools/call request

Available Tools

Tool Name	Description
get_calendar_status	Calendar utilization, open status, and next available slot
list_services	List bookable services with duration and type
list_appointments	Look up a caller's appointments
check_availability	Check available time slots using natural language
book_appointment	Book an appointment with caller details
cancel_appointment	Cancel an existing appointment
reschedule_appointment	Reschedule an appointment to a new time
request_callback	Request a callback when the bot can't resolve the issue

The tool parameters largely mirror the REST endpoints; your platform sees the exact description of each parameter via tools/list. The main differences and required fields:

check_availability expects the natural language query in the checkAvail parameter (required), plus optionally serviceName or serviceNames and language.
book_appointment expects bookAppointment (ISO 8601 timestamp) and callerName (both required), plus optionally callerPhone, callerIdNumber, reason, serviceName or serviceNames, and language.
reschedule_appointment expects newDateTime (required); it finds the existing appointment via callerIdNumber, callerPhone, callerName, or appointmentDate.
cancel_appointment and reschedule_appointment respond with verification_required when the caller needs to provide a 4-digit code sent by SMS — pass it as verificationCode on the next call.

Results come back as JSON text in the content of the tool response.

Testing with curl

curl -X POST "https://api.flowcaptain.com/mcp?calendarId=YOUR_CALENDAR_ID" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": { "name": "test", "version": "1.0" }
    }
  }'

When to Use MCP vs. REST

Both offer the same functionality. MCP discovers all tools automatically through a single endpoint, while REST uses separate endpoints per action. We recommend MCP whenever your platform supports it — setup is faster, and new tools become available automatically without changing your integration.