LobbyStack

npx add-mcp 'https://app.lobbystack.com/api/mcp'

Run your agent from an AI assistant

Connect Claude, ChatGPT and other MCP clients to LobbyStack to read calls, book appointments and update what your agent knows.

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

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, 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.

[accordion] 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 agent took for your team
add_knowledge	knowledge:write	Adds an FAQ or a text entry the agent can use

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:

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 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:

{ "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 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.

This documentation is built and hosted on Mintlify, a developer documentation platform.