> ## Documentation Index > Fetch the complete documentation index at: https://docs.lobbystack.com/llms.txt > Use this file to discover all available pages before exploring further. # Run your receptionist from an AI assistant > Connect Claude, ChatGPT and other MCP clients to LobbyStack to read calls, book appointments and update what your receptionist 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](/api/overview). 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 ` | 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](/api/authentication). Follow the guide for [Claude](/ai/connect-claude), [ChatGPT](/ai/connect-chatgpt) or [another MCP client](/ai/connect-other-clients). ## Sign in with LobbyStack LobbyStack runs an OAuth 2.1 authorization server for MCP clients, as the [MCP authorization spec](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization) 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. 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 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. | 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](/api/requests): ```json theme={null} { "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](/ai/lobbystack-skill) explains the tools, common workflows and error handling in a form you can give to an agent as instructions.