Guesty MCP Server (beta)

❗️

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 API Support Team .

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
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 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

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

https://mcp.guesty.com/v1

Local stdio (recommended)

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

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

OAuth2 client credentials (token exchange at server startup):

{
  "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:

"args": ["-y", "@guestyorg/[email protected]", "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

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:

{
  "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.

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

Alternative — hosted with Authorization header

{
  "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
File (Windows): %APPDATA%\Claude\claude_desktop_config.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:

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

2. After connecting, ask the assistant to authenticate, for example:
   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
User: Command Palette → MCP: Open User Configuration

Recommended — local stdio

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

Alternative — hosted

{
  "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
Open via the agent panel → Manage MCP Servers → View raw config.

Recommended — local stdio

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

Alternative — hosted

Antigravity uses serverUrl for remote MCP servers:

{
  "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

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.

{
  "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 BEARER_TOKEN in env, or hosted with Authorization 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

• Client setup — developer wiring, local builds, and CLI usage
• Configuration — environment variables and auth modes