Authentication & Scopes

The Booked55 MCP server supports two authentication methods: OAuth 2.0 for interactive AI clients like ChatGPT and Claude, and API keys for programmatic access.

OAuth 2.0 (ChatGPT, Claude & other AI clients)

When you connect ChatGPT, Claude or another AI client you sign in to, the MCP server uses the OAuth 2.0 Authorization Code flow with PKCE (Proof Key for Code Exchange). This is the same standard used by Google, GitHub, and other major platforms.

How the flow works

Authorise: Your AI client redirects you to the Booked55 login page with a client_id, redirect_uri, requested scope, and a code_challenge.
Login & consent: You sign in with your Booked55 credentials, review the requested permissions and click Authorize.
Callback: Booked55 redirects back to the AI client with an authorization code.
Token exchange: The AI client exchanges the code (plus the code_verifier) for an access token and refresh token.
API calls: The AI client includes the access token in every MCP tool call. When it expires, the refresh token is used to get a new one.

OAuth endpoints

Endpoint	URL	Purpose
Authorise	`/oauth/authorize`	Start the login flow
Token	`/oauth/token`	Exchange code for tokens
User Info	`/oauth/userinfo`	Get current user profile
Introspect	`/oauth/introspect`	Validate a token (RFC 7662)
Revoke	`/oauth/revoke`	Revoke a token (RFC 7009)

API Key (programmatic access)

For scripts, automations, or non-browser AI clients, you can authenticate with an API key instead of OAuth.

In the Booked55 sidebar, go to Workspace → Workspace Settings → Advanced → API Keys. Only owners and managers see this page.
Click Create API Key.
Enter a Key Name, set an Expiration Date, and click Create Key.
Copy the key (it starts with vg_). It is shown in full only once.

Pass it in the Authorization header:

Authorization: Bearer vg_your_api_key_here

Scopes

Scopes control what the MCP server is allowed to do on your behalf. When you authorise via OAuth, you approve the requested scopes, and the token is refused on anything outside them. There are 22: read, write and delete for seven kinds of record — contacts, companies, tasks, events, deals, pipelines and notes — plus send:email, the consent to send outreach from your mailbox. A write consent never implies a delete, and no data scope implies sending.

Scope	What it allows
`read:contacts`	List, search and open contacts.
`write:contacts`	Create and update contacts. It also covers the surfaces that share the contact permission — campaigns, newsletters, sequences, client types, email templates, CSV import and AI enrichment — including adding people to a campaign, sequence or newsletter and taking one back off. It deletes no whole campaign, sequence, newsletter or template, and it sends nothing.
`send:email`	Send campaign, newsletter and sequence email from your connected mailbox: launching a campaign or newsletter issue, sending a test email, and activating, resuming or enrolling people in a sequence. Each of those also needs `write:contacts`. The AI shows you what will go out and asks before it sends. It does not cover a one-off email.
`delete:contacts`	Delete contacts. `write:contacts` does not imply it.
`read:companies`	List, search and open companies.
`write:companies`	Create and update companies.
`delete:companies`	Delete companies.
`read:tasks`	List and open tasks, including a recorded meeting's transcript and AI summary — those ride on the task record, so the task read scope reaches them.
`write:tasks`	Create and update tasks, including marking one complete. Completing a task and editing one are the same permission, so there is no separate completion consent.
`delete:tasks`	Delete tasks, one at a time or in bulk.
`read:events`	List, search and open events.
`write:events`	Create and update events.
`delete:events`	Delete events.
`read:deals`	List and open deals.
`write:deals`	Create and update deals.
`delete:deals`	Delete deals.
`read:pipelines`	Read pipelines, their stages, the cards on them, and pipeline analytics.
`write:pipelines`	Put a contact on a pipeline and move cards between stages.
`delete:pipelines`	Remove a card from a board. It does not delete a pipeline or a stage — that is `manage:pipelines`.
`manage:pipelines`	Change the structure everyone works from: create, rename, reorder and delete pipelines and their stages. No read, write or delete scope implies it.
`read:notes`	Read the notes on any record you can see. A note is its own kind of record, so this is separate from the read scope of the thing the note is about.
`write:notes`	Write, edit and delete notes. There is no separate delete scope, because a note may only be changed or removed by the person who wrote it, an owner or a manager — whatever the token holds.

Those 22 are the whole list a client may ask for and you may grant. A few scope names are accepted if a client presents them but cannot be requested and grant nothing on their own: openid, profile, email and offline_access are OpenID Connect identity scopes, and complete:tasks is a historical name that satisfies nothing — completing a task needs write:tasks.

If you connected your AI client before send:email existed, it can build campaigns, sequences and newsletters but not send them. Disconnect and connect it again once, and approve send:email on the consent screen.

Ready to get started?

Create your free Booked55 account and start managing your sales pipeline in minutes.

Get Started Free Learn More