Getting Started

Get up and running with the FrontDeskOS MCP Server in under 5 minutes.

Overview

FrontDeskOS is a Model Context Protocol (MCP) server that gives AI agents the ability to manage front desk operations. It exposes 50+ tools for handling incoming calls, scheduling appointments, managing leads, pulling analytics, and configuring your front desk workflows -- all through a standardized MCP interface.

Prerequisites

Node.js 18+ or Bun 1.0+
A FrontDeskOS account with an API key
An MCP-compatible client (Claude Desktop, custom agent, etc.)

Installation

Install the FrontDeskOS MCP server package using your preferred package manager:

Terminalbash

# Using npm
npm install @frontdeskos/mcp-server

# Using bun
bun add @frontdeskos/mcp-server

# Using pnpm
pnpm add @frontdeskos/mcp-server

Quick Configuration

Add FrontDeskOS to your MCP client configuration. For Claude Desktop, update your claude_desktop_config.json:

claude_desktop_config.jsonjson

{
  "mcpServers": {
    "frontdeskos": {
      "command": "npx",
      "args": ["@frontdeskos/mcp-server"],
      "env": {
        "FRONTDESK_API_KEY": "sk_live_your_api_key_here",
        "FRONTDESK_WORKSPACE_ID": "ws_your_workspace_id"
      }
    }
  }
}

Environment Variables

You can also set FRONTDESK_API_KEY and FRONTDESK_WORKSPACE_ID as system environment variables instead of including them in the configuration file.

Your First Tool Call

Once configured, your AI agent can start using FrontDeskOS tools. Here is an example of listing today's calls:

Example tool calltypescript

// The AI agent calls this tool through the MCP protocol
const result = await mcp.callTool("frontdesk_list_calls", {
  date: "2025-01-15",
  status: "completed",
  limit: 10
});

Tool response

200 OK

{
  "calls": [
    {
      "id": "call_01abc",
      "caller_name": "John Smith",
      "caller_phone": "+1-555-0123",
      "duration_seconds": 142,
      "status": "completed",
      "summary": "Scheduled annual check-up for Jan 22",
      "sentiment": "positive",
      "created_at": "2025-01-15T09:30:00Z"
    },
    {
      "id": "call_02def",
      "caller_name": "Jane Doe",
      "caller_phone": "+1-555-0456",
      "duration_seconds": 87,
      "status": "completed",
      "summary": "Rescheduled appointment from Jan 18 to Jan 25",
      "sentiment": "neutral",
      "created_at": "2025-01-15T10:15:00Z"
    }
  ],
  "total": 2,
  "has_more": false
}

Programmatic Usage

You can also run the FrontDeskOS MCP server programmatically in your own application:

server.tstypescript

import { FrontDeskMCPServer } from "@frontdeskos/mcp-server";

const server = new FrontDeskMCPServer({
  apiKey: process.env.FRONTDESK_API_KEY!,
  workspaceId: process.env.FRONTDESK_WORKSPACE_ID!,
  transport: "stdio", // or "sse" for HTTP transport
});

// Start listening for MCP requests
await server.start();
console.log("FrontDeskOS MCP server running");

Transport Options

FrontDeskOS supports both stdio (for local clients like Claude Desktop) and sse (Server-Sent Events for remote HTTP connections). See the Authentication page for details on securing SSE transport.

Next Steps

Authentication -- Configure API keys and OAuth
Tools Reference -- Explore all 50+ available tools
Retell AI Guide -- Set up voice AI integration
Claude Desktop Guide -- Full Claude Desktop walkthrough