Run your receptionist from an AI assistant

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.

Connect

Setting	Value
Server URL	`https://app.lobbystack.com/api/mcp`
Transport	Streamable HTTP
Authentication	Sign in with LobbyStack (OAuth), or `Authorization: Bearer <API key>`

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 and ChatGPT connectors.
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 let you set request headers. See Authentication.

Follow the guide for Claude, ChatGPT or another MCP client. 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:

Sign in, if you aren’t signed in already.
Pick the business. You see only businesses where you’re an owner or admin.
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 in Settings > Connected apps, with who connected it, its permissions, 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.

Details for MCP client developers

Item	Value
Protected resource metadata	`/.well-known/oauth-protected-resource/api/mcp`
Authorization server issuer	`https://app.lobbystack.com/api/auth`
Authorization server metadata	`/.well-known/oauth-authorization-server/api/auth`
Client registration	Client ID Metadata Documents (HTTPS `client_id`) or dynamic client registration at `/api/auth/oauth2/register`
Grants	`authorization_code` with PKCE (`S256`, required), `refresh_token`
Resource indicator	Send `resource=https://app.lobbystack.com/api/mcp`. Tokens for other resources are rejected.
Scopes	The tool scopes in the table below, plus `offline_access` for refresh tokens
Revocation	`/api/auth/oauth2/revoke` (RFC 7009)

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

Tool	Scope	What it does
`get_business`	`business:read`	Business name, time zone, opening hours and booking mode
`list_services`	`business:read`	Services customers can book
`list_staff`	`business:read`	People who take appointments and the services they do
`update_business_hours`	`business:write`	Replaces the week’s opening hours
`list_calls`	`calls:read`	Calls newest first, filtered by start time
`get_call`	`calls:read`	One call with its transcript
`search_contacts`	`contacts:read`	Contacts by phone, email or part of the name
`get_contact`	`contacts:read`	One contact
`create_contact`	`contacts:write`	Adds a contact
`update_contact`	`contacts:write`	Changes a contact’s details
`list_appointments`	`appointments:read`	Appointments filtered by status, start time or contact
`get_appointment`	`appointments:read`	One appointment
`check_availability`	`appointments:read`	Open times for a service, up to 7 days, for anyone or one staff member
`book_appointment`	`appointments:write`	Books an open time
`cancel_appointment`	`appointments:write`	Cancels an appointment
`reschedule_appointment`	`appointments:write`	Moves an appointment to another open time or staff member
`list_messages`	`messages:read`	Messages the receptionist took for your team
`add_knowledge`	`knowledge:write`	Adds an FAQ or a text entry the receptionist can use

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 Appointments is set to Books appointments (booking_mode instant). In other modes they return an error instead of booking:

Setting	`booking_mode`	Error code	What the assistant should do
Takes requests	`request`	`booking_requires_confirmation`	Tell you your team confirms requests from the inbox
Doesn’t book	`off`	`booking_disabled`	Tell you booking is turned off

You change this setting under Agent > AI settings > Booking. 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:

{ "error": { "code": "slot_unavailable", "message": "That time is not available. Pick another time from GET /availability." } }

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 in Settings > Connected apps, or revoke its key in Settings > API keys.

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.

Get started

General

Agent

Manage

API

AI assistants

API reference

Self-hosting

Run your receptionist from an AI assistant

Connect

Tools

Booking mode

Errors

Limits and retries

Audit log

Guide for AI agents

​Connect

​Sign in with LobbyStack

​Tools

​Booking mode

​Errors

​Limits and retries

​Audit log

​Guide for AI agents

Connect

Sign in with LobbyStack

Tools

Booking mode

Errors

Limits and retries

Audit log

Guide for AI agents