Connect through MCP

MCP lets Claude Code read your villas, bookings, customers and availability, and create customers or hourly and overnight bookings in VillaSlot. You connect through OAuth: sign in, choose an organization and approve the requested access. Your agent can only use the data and actions you authorize.

Connect your MCP client

Add this server URL to your MCP client:

https://www.villaslot.io/api/mcp

Start the OAuth connection, sign in with your password or Google, and review the application, requested permissions and organization before selecting Allow. An application registered dynamically is shown as unverified. OAuth public clients use PKCE; offline_access maintains the connection with refresh tokens. Access tokens expire after 15 minutes.

Choose the staff organization explicitly on the consent screen. Your last active organization is preselected only while you still have staff access; otherwise choose one, even if only one is available. This does not change your active browser organization. The authorization stays bound to the chosen organization. Membership, bans, disabled clients and revocation are checked on every request. Reconnecting creates a new grant and never revives old tokens.

Claude Code

With Claude Code installed, run these commands in your terminal:

claude mcp add --transport http --scope user villaslot https://www.villaslot.io/api/mcp
claude mcp login villaslot

Your browser opens for OAuth. Sign in to VillaSlot, choose the organization, review the requested permissions, then select Allow. The user scope makes this configuration available across your projects on this machine.

Then open Claude Code:

claude

Enter /mcp inside the Claude Code conversation to check the villaslot server. If your version does not offer claude mcp login, use /mcp, select villaslot, and start its authentication flow there.

Codex

With the Codex CLI installed, add the server:

codex mcp add villaslot --url https://www.villaslot.io/api/mcp

Codex may offer OAuth sign-in immediately after adding the server. If you have not completed it, run:

codex mcp login villaslot

In your browser, sign in to VillaSlot, choose the organization, review the permissions and select Allow. Then open a new session:

codex

Enter /mcp inside Codex to see the available servers. This OAuth connection does not require a VillaSlot API key or an Authorization header to copy.

Check the connection

In Claude Code or Codex, ask:

Use the villaslot MCP to list my villas.
State which organization you are using. Do not change any data.

Check that the returned organization matches the one you authorized. An already open session may need a restart to load the new server.

References: MCP in Claude Code and MCP in Codex.

Tools

Inputs and results

Lists accept limit (default 25, maximum 100), offset (0–10000) and search (maximum 200 characters). list_villas accepts status: active, archived or all. list_bookings accepts axis: UPCOMING or RECENT, and an optional propertyId.

get_availability accepts kind: HOURLY, a villa, a local calendar date and a supported durationMinutes; or kind: OVERNIGHT with checkInDay and checkOutDay. Stays are limited to 366 nights and must respect the organization’s minimum stay. Dates use the organization’s timezone, returned where relevant. Monetary amounts are integer minor units paired with a currency: do not divide or multiply them implicitly.

create_customer accepts a name and optional email, phone and notes. create_booking accepts villa/customer IDs, date, start minute, duration and status (HOLD or CONFIRMED); price and deposit percentage are optional. create_overnight_booking requires a total priceAmount alongside villa/customer IDs, arrival/departure dates and status. The total is not calculated from the nightly rate.

Creates use the same role permissions, subscription limits, pricing, buffer, availability and Airbnb conflict rules as the application. They are not idempotent: do not automatically retry an uncertain creation. Read back the result first. Each result identifies the authorized organization. Responses omit client-link tokens, payment credentials and financial-report aggregates.

If a call is refused because a personal right is disabled, re-enable that right in MCP agents and select Save; you do not need to reconnect. A revoked or expired grant requires a new OAuth consent flow from your MCP client. If you have lost organization membership, first restore membership with an eligible staff role, then reconnect to authorize access. Restart an expired consent request from the client. Registration, magic links and backup codes are not supported during this OAuth login flow.

Personal rights, limits and connected apps

Open Account → MCP agents to see connected applications, redirect hosts, scopes and organizations. Revoke disconnects an app from all your organizations immediately, including access and refresh tokens. You can revoke even after leaving all staff organizations.

The three personal switches, Read data, Create bookings and Create customers, control these actions across your apps. Select Save to apply changes on the next call without reconnecting. OAuth scopes, staff permissions and plan limits still apply. Disabled families return MCP_RIGHTS_DENIED, without an OAuth login loop.

The daily limit applies independently per organization across all your apps: empty means unlimited, zero blocks creation. Each committed customer, hourly booking or overnight booking counts as one; reading is free. A later response or activity failure does not erase committed usage. MCP_DAILY_LIMIT means the personal cap was reached. The accounting day is fixed at call admission in the organization timezone (UTC when unset). An invalid timezone blocks creation until corrected; settings and revocation remain available.