Skip to main content
LobbyStack runs a Model Context Protocol (MCP) server. Connect an AI assistant to it and ask in plain language: “Who called yesterday and didn’t book?”, “Book Dana Whitfield for a cleaning on Tuesday morning”, or “Close on Saturdays from now on.” The assistant works through the same rules as the REST API. It sees one business, it can do only what its API key allows, and every change it makes lands in the business’s audit log. White label partners can connect an assistant to their partner instead of one business. It then gets the partner console’s tools too, and passes a business_id to each tool below. See Run the partner console from an AI assistant.

​
Connect

Self-hosted deployments serve the same path on their own domain, for example https://lobbystack.example.com/api/mcp. Assistants connect one of two ways:
  • Sign in with LobbyStack. Add the server URL to the assistant. It opens a LobbyStack page where you sign in, pick the business, and choose what the assistant can do. Use this for Claude, ChatGPT, Claude Code, Codex, Cursor and VS Code.
  • API key. Create a key in Settings > API keys and put it in the assistant’s configuration. Use this for scripts, CI, and clients that can’t sign in with OAuth but let you set request headers. See Authentication.
Follow the guide for Claude, ChatGPT or another MCP client.

​
Sign in with LobbyStack

LobbyStack runs an OAuth 2.1 authorization server for MCP clients, as the MCP authorization spec describes. Your assistant finds it on its own from the server URL. When you connect, LobbyStack asks you to:
  1. Sign in, if you aren’t signed in already.
  2. Pick the business. You see only businesses where you’re an owner or admin. If you’re on a white label partner’s team, you can pick the partner under Your agencies instead.
  3. Choose what the assistant can do. Every permission it asked for starts checked; uncheck the ones you don’t want.
The assistant then gets access to that one business. Access tokens last an hour, and the assistant renews them for up to 30 days of inactivity without asking you again. Each renewal replaces the previous refresh token, and reusing an old one ends the connection. Owners and admins see every connected assistant for the business under MCP connections in Settings > API keys, with who connected it and when it last made a request. Click Disconnect to cut it off right away. If the person who connected it stops being an owner or admin, the connection stops working too.
A 401 from /api/mcp carries WWW-Authenticate: Bearer resource_metadata="...". Clients with loopback redirect URIs, such as http://127.0.0.1:6276/callback, register as native apps; other redirect URIs must use HTTPS.

​
Tools

On a partner connection each of these tools also takes business_id, and the partner tools listed in Run the partner console from an AI assistant come on top. Scopes are the same for OAuth and API keys. Tools return the same objects as the REST API, with times in UTC. Read-only tools carry the readOnlyHint annotation, and tools that cancel, move or replace data carry destructiveHint, so your assistant can ask you before it runs them. The webhooks:manage scope has no MCP tools. A key with only that scope can’t connect.

​
Booking mode

book_appointment and reschedule_appointment work only when Booking is set to Books appointments (booking_mode instant). In other modes they return an error instead of booking: You change this setting on each agent’s General page, under Appointments. /receptionist and the MCP tools change the default agent. Cancelling works in every mode.

​
Errors

A failed tool call returns a result marked as an error. Its text is JSON with the same codes as the REST API:
The server itself answers 401 when the key or access token is missing, unknown, expired or revoked, and 403 when it has no scope the MCP server uses.

​
Limits and retries

Each tool call counts against a limit of 120 requests per minute. An API key shares its limit with REST requests made with the same key; each OAuth connection has its own. Listing tools doesn’t count. Past the limit, the tool returns rate_limited with the seconds to wait. book_appointment, create_contact and add_knowledge accept an optional idempotency_key. Retry with the same value within 24 hours and you get the first result back instead of a duplicate. These keys are the same as the REST Idempotency-Key for POST /appointments, POST /contacts and POST /knowledge: a retry through MCP of a REST request, or the reverse, returns the first result. The same key with different details returns idempotency_key_reused.

​
Audit log

LobbyStack records each change made through the MCP server in the business’s audit log with the actor mcp and the API key’s ID, or for OAuth, the connection’s ID and the person who approved it. It never logs keys or tokens. To cut off an assistant, disconnect it under MCP connections in Settings > API keys, or revoke its key on the same page.

​
Guide for AI agents

The LobbyStack skill explains the tools, common workflows and error handling in a form you can give to an agent as instructions. To set up a receptionist from scratch, paste a setup prompt into your assistant.