1. Guesty Help Center
  2. Pilot / Beta
  3. Other releases

Beta: Connecting MCP-compatible AI assistants to your Guesty account

This article explains how to connect Model Context Protocol (MCP)-compatible AI assistants to your Guesty account using the Guesty MCP Server. This allows assistants like Cursor, Claude Desktop, and VS Code to retrieve and reason about the Guesty data you're authorized to access.

Important:

Guesty MCP Server is an experimental feature in an early-stage beta release. Do not rely on it for any production use. During this phase, the server only allows read-only access, meaning assistants can look up and summarize data but cannot create, update, or delete Guesty records.

Overview of Guesty MCP server

The server exposes supported Guesty features as MCP tools. Your AI assistant can only use the tools that are registered on the MCP server and authenticated with your Guesty API credentials.

Typical use cases include:

  • 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

Before you begin

  • You'll need your Guesty API client_id and client_secret.
  • For the recommended local connection method, you must have Node.js 20 or later installed and available on your system PATH.

Get your Guesty API token

To connect your assistant, you first need a Guesty API bearer token. You can get this by exchanging your OAuth client credentials for an access token.

Your client_id and client_secret are available in your Guesty account. For more information, see our article on Using Guesty's Open API.

Note:

If you configure your MCP client to use your CLIENT_ID and CLIENT_SECRET directly, you can skip the manual token exchange step.

  1. Run the following curl command in your terminal, replacing your-client-id and your-client-secret with your actual credentials.

  2. 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"
  3. A successful request returns a response like this:

  4. JSON

    {
  "token_type": "Bearer",
  "access_token": "eyJ...",
  "expires_in": 86400
}
  5. Copy the access_token value. This is the bearer token you'll use to configure your client. Tokens typically expire after 24 hours.

Note:

To avoid hitting API rate limits, reuse your Guesty tokens until they expire.

Choose a connection method

You can connect to the Guesty MCP Server in two ways: locally via stdio or through a hosted HTTP endpoint. We recommend the local stdio setup for most users as it keeps your credentials out of chat prompts.

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

Connect your MCP client

Follow the instructions below for your specific AI assistant client.

Connect Cursor

  1. Open your MCP configuration file, located at ~/.cursor/mcp.json (for user settings) or in your project's MCP configuration.
  2. Add one of the following configurations:
    Recommended — Local stdio

  3. JSON

    {
  "mcpServers": {
    "guesty": {
      "command": "npx",
      "args": ["-y", "@guestyorg/sdk", "mcp"],
      "env": {
        "BEARER_TOKEN": "eyJ..."
      }
    }
  }
}
  4. Alternative — Hosted with Authorization header

  5. JSON

    {
  "mcpServers": {
    "guesty": {
      "url": "https://mcp.guesty.com/v1",
      "headers": {
        "Authorization": "Bearer your-guesty-token"
      }
    }
  }
}
  6. Restart Cursor and verify that the Guesty server appears as connected under "Settings → MCP".

Back to the top

Connect Claude Desktop

  1. Open the Claude Desktop configuration file.
    1. macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    2. Windows: %APPDATA%\Claude\claude_desktop_config.json
  2. Add one of the following configurations:
    Recommended — Local stdio

  3. JSON

    {
  "mcpServers": {
    "guesty": {
      "command": "npx",
      "args": ["-y", "@guestyorg/sdk", "mcp"],
      "env": {
        "BEARER_TOKEN": "eyJ..."
      }
    }
  }
}
  4. Alternative — Hosted
    Since Claude Desktop doesn't support custom headers in its MCP configuration, you must authenticate for each session.
    1. Add the following to your configuration file:

    2. JSON

      {
  "mcpServers": {
    "guesty": {
      "url": "https://mcp.guesty.com/v1"
    }
  }
}
    3. After connecting, ask the assistant to authenticate by sending a message like: My Guesty token is eyJ... — please authenticate.
    4. The assistant will use the set_token tool to store the token for the current session. You must repeat this for each new session.

Back to the top

Connect VS Code (GitHub Copilot)

  1. Open your MCP configuration file.
    • Workspace: .vscode/mcp.json
    • User: Open the "Command Palette" and select "MCP: Open User Configuration".
  2. Add one of the following configurations inside the servers object:
    Recommended — Local stdio

  3. JSON

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

  5. JSON

    {
  "servers": {
    "guesty": {
      "type": "http",
      "url": "https://mcp.guesty.com/v1",
      "headers": {
        "Authorization": "Bearer your-guesty-token"
      }
    }
  }
}
  6. Reload the window or restart the MCP host. Confirm Guesty is listed and connected in the Copilot Chat MCP settings.

Back to the top

Connect Google Antigravity

  1. Open your MCP configuration file, located at ~/.gemini/config/mcp_config.json. You can also open it from the agent panel by selecting "Manage MCP Servers → View raw config".
  2. Add one of the following configurations:
    Recommended — Local stdio

  3. JSON

    {
  "mcpServers": {
    "guesty": {
      "command": "npx",
      "args": ["-y", "@guestyorg/sdk", "mcp"],
      "env": {
        "BEARER_TOKEN": "eyJ..."
      }
    }
  }
}
  4. Alternative — Hosted

  5. JSON

    {
  "mcpServers": {
    "guesty": {
      "serverUrl": "https://mcp.guesty.com/v1",
      "headers": {
        "Authorization": "Bearer your-guesty-token"
      }
    }
  }
}
  6. Restart Antigravity after editing. On macOS, if the IDE cannot find npx, use the full path to npx (e.g., /opt/homebrew/bin/npx) in the command field.

Back to the top

Advanced: Using OAuth2 Client Credentials

As an alternative to using a bearer token, you can provide your CLIENT_ID and CLIENT_SECRET directly in the configuration. The server will perform the token exchange at startup.

JSON

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

Back to the top

Advanced: Pinning a Release Version

To ensure reproducible behavior, you can pin a specific version of the Guesty SDK in the args array.

JSON

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

Back to the top

How to Use the Connection

Once your client is connected and authenticated, you can ask your assistant questions about your Guesty data. The assistant automatically discovers the available Guesty tools and uses them when needed to answer your prompts.

Example prompts:

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

Security Best Practices

  • Keep your Guesty bearer token secure, as it grants API access to your account.
  • Prefer using the local stdio method with BEARER_TOKEN in env or the hosted method with Authorization headers. This prevents tokens from being visible in your chat history.
  • If you must use the set_token tool, avoid pasting tokens in shared or recorded sessions.
  • Do not pass tokens as URL query parameters.
  • Do not commit MCP configuration files containing live tokens to version control.
  • Rotate your credentials according to your organization's security policy.

Managed Deployments

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

JSON

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

Contact Guesty to set up a managed deployment.

How the Server Uses Your Token

The token used for Guesty API calls is determined by how it's provided. All API calls within a session use the token bound to that session, and sessions are isolated from each other.

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
Was this article helpful?
0 out of 0 found this helpful