MCP Endpoint

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

MCP Endpoint

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 Dashboard → Calendar → API → 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 mirror the REST endpoints: check_availability expects the natural language query in the checkAvail parameter; book_appointment expects bookAppointment (ISO 8601 timestamp) and callerName, plus optionally callerPhone, callerIdNumber, reason, serviceName, and language.

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.