---
updatedAt: 2026-08-22T07:52:13.000Z
agentTools:
  projectIndex: https://open-api-docs.guesty.com/llms.txt
---

# Guesty MCP Server (beta)

Guesty MCP Server enables MCP-compatible AI assistants to connect to Guesty API

<Callout icon="❗️" theme="error">
  **Experimental**

  Guesty MCP Server is currently in an early-stage beta release and should be considered experimental. Do not rely on it for any production use until this designation is removed.

  You are welcome to test it and report any issues or bugs to our <Anchor target="_blank" href="https://help.guesty.com/hc/en-gb/articles/9370047984413-Contacting-Customer-Experience">API Support Team</Anchor> .
</Callout>

<br />

Guesty MCP Server enables MCP-compatible AI assistants to connect to Guesty through a controlled, authenticated tool interface. It is designed for customers and partners who want assistants such as Cursor, Claude Desktop, VS Code, or Google Antigravity to retrieve and reason about Guesty data they are authorized to access.

> **Beta — read-only**<br />Guesty MCP Server is currently in beta. During this phase, the server exposes **read endpoints only** — assistants can look up and summarize data, but cannot create, update, or delete Guesty records. Tool coverage, schemas, and availability may change before general availability.

## Overview

The server exposes supported Guesty features as [Model Context Protocol](https://modelcontextprotocol.io/) tools. Assistants can only use tools registered on the MCP server and authenticated with your Guesty API credentials. They do not receive unrestricted API access.

**During the beta, all tools are read-only.** Each tool maps to a Guesty GET operation. Write operations (create, update, delete) are not available in this phase.

Typical use cases:

* Looking up supported Guesty records from an assistant
* Summarizing reservation, property, or guest information
* Investigating operational questions using authorized Guesty data
* Reducing manual lookups while keeping API credentials out of chat prompts

## Connection options

| Mode                                | Endpoint / command          | Best for                                                                 |
| ----------------------------------- | --------------------------- | ------------------------------------------------------------------------ |
| **Local (stdio)** — **recommended** | `npx -y @guestyorg/sdk mcp` | Default for all supported clients; credentials in `env`; pin SDK version |
| **Hosted (HTTP)**                   | `https://mcp.guesty.com/v1` | No Node.js on the machine, or Guesty-managed deployment                  |

**We recommend the local stdio setup** for most users. It runs via `npx` — you do not install or publish a separate Guesty package. The MCP client spawns the server as a subprocess and passes your token through environment variables, which keeps secrets out of chat and works consistently across Cursor, Claude Desktop, VS Code, and Antigravity.

Use the **hosted endpoint** when Node.js is not available to your MCP client, when Guesty operates credentials on your behalf, or when your organization standardizes on a single remote MCP URL.

**Requirements for local stdio:** Node.js 20 or later must be installed and available on your system `PATH` (Node includes `npx`). Many MCP clients already satisfy this when you run other `npx`-based servers.

### Hosted endpoint

```text
https://mcp.guesty.com/v1
```

### Local stdio (recommended)

Add this block to your client’s MCP configuration (see per-client paths below):

```json
{
  "mcpServers": {
    "guesty": {
      "command": "npx",
      "args": ["-y", "@guestyorg/sdk", "mcp"],
      "env": {
        "BEARER_TOKEN": "eyJ..."
      }
    }
  }
}
```

**OAuth2 client credentials** (token exchange at server startup):

```json
{
  "mcpServers": {
    "guesty": {
      "command": "npx",
      "args": ["-y", "@guestyorg/sdk", "mcp"],
      "env": {
        "CLIENT_ID": "your-client-id",
        "CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
```

Pin a release for reproducible behavior:

```json
"args": ["-y", "@guestyorg/sdk@0.2.0", "mcp"]
```

After saving configuration, restart your MCP client and confirm Guesty appears as connected in that client’s MCP settings.

## Getting a Guesty token

Before connecting, obtain a Guesty API bearer token by exchanging your OAuth client credentials for an access token.

> Note: If you use your CLIENT\_ID, CLIENT\_SECRET there is no need to manually get token.

### Token exchange

```bash
curl -s -X POST https://open-api.guesty.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=your-client-id" \
  -d "client_secret=your-client-secret" \
  -d "scope=open-api"
```

Successful response:

```json
{
  "token_type": "Bearer",
  "access_token": "eyJ...",
  "expires_in": 86400
}
```

Use the `access_token` value as your bearer token. Tokens expire after `expires_in` seconds (typically 24 hours). Request a new token before it expires.

Your `client_id` and `client_secret` are available in your Guesty account under API access or integration settings. Do not share these credentials. Use them only to obtain tokens. Never include them in assistant conversations.

> Note: Ensure to reuse your Guesty tokens, pass to Agent or to MCP to avoid hitting AS rate limits.

## Connect your MCP client

### Cursor

**Recommended — local stdio**

File: `~/.cursor/mcp.json` (user) or your project MCP configuration.

```json
{
  "mcpServers": {
    "guesty": {
      "command": "npx",
      "args": ["-y", "@guestyorg/sdk", "mcp"],
      "env": {
        "BEARER_TOKEN": "eyJ..."
      }
    }
  }
}
```

**One click install:**

[<Image src="https://cursor.com/deeplink/mcp-install-light.svg" alt="Install Guesty MCP in Cursor" align="left" wrap={true} />](https://cursor.com/en-US/install-mcp?name=guesty\&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBndWVzdHlvcmcvc2RrIiwibWNwIl0sImVudiI6eyJCRUFSRVJfVE9LRU4iOiJZT1VSX0dVRVNUWV9UT0tFTiJ9fQ%3D%3D)

<br />

<br />

After clicking, replace `YOUR_GUESTY_TOKEN` in the install dialog with your bearer token, then confirm installation.

**Alternative — hosted with Authorization header**

```json
{
  "mcpServers": {
    "guesty": {
      "url": "https://mcp.guesty.com/v1",
      "headers": {
        "Authorization": "Bearer your-guesty-token"
      }
    }
  }
}
```

The server reads the token from the header when the MCP session initializes. Each session is isolated.

Restart Cursor and verify a connected Guesty server under **Settings → MCP**.

### Claude Desktop

**Recommended — local stdio**

File (macOS): `~/Library/Application Support/Claude/claude_desktop_config.json`<br />File (Windows): `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "guesty": {
      "command": "npx",
      "args": ["-y", "@guestyorg/sdk", "mcp"],
      "env": {
        "BEARER_TOKEN": "eyJ..."
      }
    }
  }
}
```

**Alternative — hosted**

Claude Desktop does not support custom `headers` in MCP configuration. Use the hosted URL and authenticate per session:

1. Configuration:

```json
{
  "mcpServers": {
    "guesty": {
      "url": "https://mcp.guesty.com/v1"
    }
  }
}
```

2. After connecting, ask the assistant to authenticate, for example:<br />`My Guesty token is eyJ... — please authenticate`

3. The assistant calls the `set_token` tool, which stores the token for the current session.

You must repeat step 3 for each new session unless conversation context is restored. Prefer local stdio when possible to avoid pasting tokens in chat.

### VS Code (GitHub Copilot)

VS Code uses a `servers` object in `mcp.json` (not top-level `mcpServers`).

**Workspace:** `.vscode/mcp.json`<br />**User:** Command Palette → **MCP: Open User Configuration**

**Recommended — local stdio**

```json
{
  "servers": {
    "guesty": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@guestyorg/sdk", "mcp"],
      "env": {
        "BEARER_TOKEN": "eyJ..."
      }
    }
  }
}
```

**Alternative — hosted**

```json
{
  "servers": {
    "guesty": {
      "type": "http",
      "url": "https://mcp.guesty.com/v1",
      "headers": {
        "Authorization": "Bearer your-guesty-token"
      }
    }
  }
}
```

Reload the window or restart the MCP host after editing. Confirm Guesty is listed and connected in Copilot Chat MCP settings.

### Google Antigravity

Configuration file: `~/.gemini/config/mcp_config.json`<br />Open via the agent panel → **Manage MCP Servers** → **View raw config**.

**Recommended — local stdio**

```json
{
  "mcpServers": {
    "guesty": {
      "command": "npx",
      "args": ["-y", "@guestyorg/sdk", "mcp"],
      "env": {
        "BEARER_TOKEN": "eyJ..."
      }
    }
  }
}
```

**Alternative — hosted**

Antigravity uses `serverUrl` for remote MCP servers:

```json
{
  "mcpServers": {
    "guesty": {
      "serverUrl": "https://mcp.guesty.com/v1",
      "headers": {
        "Authorization": "Bearer your-guesty-token"
      }
    }
  }
}
```

Restart Antigravity after editing. On macOS, if the IDE launched from the GUI cannot find `npx`, use the full path to `npx` (for example `/opt/homebrew/bin/npx`) in `command`.

## How the server uses the token

| Source                                   | When it applies                                     |
| ---------------------------------------- | --------------------------------------------------- |
| `BEARER_TOKEN` or OAuth env (stdio)      | Applied when the MCP server process starts          |
| `Authorization` header (hosted)          | Bound at MCP session initialization                 |
| `set_token` tool (hosted, Agent Desktop) | Stored immediately for the remainder of the session |

All Guesty API calls in a session use the token bound to that session. Sessions are isolated.

## Managed deployments

For dedicated deployments where Guesty provisions credentials on the server side, connect using only the URL. No token configuration is required on the client.

```json
{
  "mcpServers": {
    "guesty": {
      "url": "https://mcp.guesty.com/v1"
    }
  }
}
```

Contact Guesty to set up a managed deployment.

## How to use

Once connected and authenticated, ask your assistant questions about supported Guesty data. The assistant discovers available Guesty tools from the MCP server and invokes the appropriate tool when your request requires Guesty data.

Example prompts:

* "Find the reservation for confirmation code ABC123."
* "Summarize this guest's current booking details."
* "Look up the property details for this listing."

Available tools and fields depend on your account permissions and current beta tool coverage. Requests that require write operations are not supported during the beta.

## Security notes

* Keep your Guesty bearer token secure. It grants API access to your Guesty account.
* **Prefer local stdio with&#x20;**`BEARER_TOKEN`**&#x20;in&#x20;**`env`, or **hosted with&#x20;**`Authorization`**&#x20;headers**, so tokens are not visible in chat.
* If using hosted with `set_token`, avoid pasting tokens in shared or recorded sessions.
* Do not pass tokens as URL query parameters. Query parameters are commonly logged by proxies and gateways.
* Do not commit MCP configuration files that contain live tokens to version control.
* Rotate credentials according to your organization's security policy.

## Beta status

Guesty MCP Server is beta software.

* **Read-only in beta:** Only read (GET) endpoints are exposed.
* Tool coverage is limited and may expand in a future release.
* Tool names, parameters, and responses may change before general availability.
* Hosted service availability may be limited during beta; local stdio via `@guestyorg/sdk` does not depend on the hosted endpoint.
* A full OAuth 2.0 authorization flow with no manual token handling is planned for general availability.

## Licensing

Unless Guesty publishes a separate license for this package, Guesty MCP Server is proprietary Guesty software. Use is subject to your agreement with Guesty and any terms that apply to the beta program.

## Related documentation

* [Getting started](https://open-api-docs.guesty.com/reference/get-started) — developer wiring, local builds, and CLI usage
* [Authentication](https://open-api-docs.guesty.com/docs/authentication) — environment variables and auth modes
* [Response and error codes](https://open-api-docs.guesty.com/reference/response-codes) — Responses and error codes