Casa Layer · Every guest, remembered.

Casa exposes a Model Context Protocol (MCP) server so AI assistants can read guest context — every guest, remembered — with the same tenant isolation as the REST API. Authenticate with API keys or MCP OAuth (Claude). It is a spec-compliant server built on the official @modelcontextprotocol/sdk, served over Streamable HTTP.

The MCP server is not a REST endpoint, so it is intentionally excluded from the API Reference. Connect with an MCP client, not curl.

Endpoint


URL	`https://api.casa-layer.com/mcp`
Transport	Streamable HTTP (stateless)
Auth	OAuth (Claude) or `Authorization: Bearer casa_…` API key (Cursor, Inspector, scripts)
Server name	`casa-guest-context`

Every tool runs scoped to the caller’s property group (or, for an API key, its pinned property) and enforces the same scopes as the REST API. Each call is audit-logged against the calling user or key. Two ways to authenticate, depending on the client:

OAuth — for clients that speak the MCP OAuth flow (Claude). The server advertises WorkOS AuthKit as its authorization server; the user signs in and consents, and the connection acts as that user in their organization with a read-only, group-scoped credential.
API key (casa_…) — for clients that send a bearer header (Cursor, MCP Inspector, programmatic SDK use). Same key as the REST API.

Tools

Eleven tools cover the guest context surface. All results are JSON matching the REST API’s response shapes.

Pagination. Every search/list tool returns { data, next_cursor, has_more }. limit sets the page size (max 500 per call), not a cap on the total: when has_more is true, call the tool again with cursor set to the previous result’s next_cursor, and repeat until next_cursor is null to retrieve the full set. (reviews_summary is an aggregate and is not paginated; the event log’s latest mode returns a single page.)

guest_event_log

Read the append-only guest event log — the full ordered change history (timeline, default) or the latest delta slice per entity (latest; rollup is a compatibility alias). Requires scope read:events.

Argument	Type	Description
`mode`	`timeline` \| `latest` \| `rollup` (optional)	History vs. latest delta slice per entity.
`entity_type`	string (optional)	Canonical entity type, e.g. `guest_profile`, `reservation`.
`entity_id`	string (optional)	Filter to a single entity.
`guest_profile_id`	string (optional)	Filter to one guest’s events.
`limit`	integer 1–500 (optional)	Page size (`timeline` only).
`cursor`	string (optional)	Pagination token from a previous `next_cursor`.

master_profile_search

Search identity-resolved master guest profiles — golden records merged across source systems. Requires scope read:guests.

Argument	Type	Description
`q`	string (optional)	Free-text match on name, email, or phone.
`limit`	integer 1–500 (optional)	Page size.
`cursor`	string (optional)	Pagination token from a previous `next_cursor`.

loyalty_members_search

Search loyalty members: each membership joined with its guest and program, ordered by points. Requires scope read:loyalty.

Argument	Type	Description
`q`	string (optional)	Free-text match on the member’s name or email.
`tier`	string (optional)	Filter by tier.
`loyalty_program_id`	string (optional)	Filter to one program.
`limit`	integer 1–500 (optional)	Page size.
`cursor`	string (optional)	Pagination token from a previous `next_cursor`.

reviews_summary

Aggregate review statistics: totals, average rating, rating distribution, per-channel breakdown, response count, and top positive/negative tags. Requires scope read:reviews.

Argument	Type	Description
`start_date`	ISO date (optional)	Reviews on/after this date.
`end_date`	ISO date (optional)	Reviews on/before this date.
`channel`	string (optional)	Channel name, e.g. Booking.com.

reservations_search

Search reservations by status, stay window, channel category, guest, or free-text guest match — newest stays first. Requires scope read:reservations.

Argument	Type	Description
`q`	string (optional)	Free-text match on the linked guest’s name or email.
`status`	string (optional)	`pending`, `confirmed`, `in_progress`, `completed`, `cancelled`, `declined`, `no_show`.
`guest_profile_id`	string (optional)	Filter to one guest.
`start_date` / `end_date`	ISO date (optional)	Stay-start window.
`channel_category`	string (optional)	`direct`, `ota`, `gds`, `corporate`, `walk_in`, `channel_manager`, `other`.
`limit`	integer 1–500 (optional)	Page size.
`cursor`	string (optional)	Pagination token from a previous `next_cursor`.

transactions_search

Search revenue transactions by guest, reservation, type, or consumption date window — newest consumption first. Requires scope read:transactions.

Argument	Type	Description
`guest_profile_id`	string (optional)	Filter to one guest.
`reservation_id`	string (optional)	Filter to one reservation.
`type`	string (optional)	Canonical type, e.g. `space`, `product`, `city_tax`.
`consumption_date_from` / `consumption_date_to`	ISO date (optional)	Consumption-date window.
`limit`	integer 1–500 (optional)	Page size.
`cursor`	string (optional)	Pagination token from a previous `next_cursor`.

consents_search

Search contact-grain consent observations by contact, purpose, status, integration, or observing guest — newest first. Email and SMS are independent. Requires scope read:consents.

Argument	Type	Description
`contact_value`	string (optional)	Exact normalized contact value.
`contact_method`	string (optional)	`email`, `sms`, `phone`, `postal`, `whatsapp`, `unknown`.
`purpose`	string (optional)	e.g. `marketing`, `transactional`.
`status`	string (optional)	`granted`, `denied`, `withdrawn`. Absence of a row means unknown.
`integration_id`	string (optional)	Filter to one integration mapping.
`guest_profile_id`	string (optional)	Observations linked to this guest at ingest.
`limit`	integer 1–500 (optional)	Page size.
`cursor`	string (optional)	Pagination token from a previous `next_cursor`.

tables_list

Enumerate ops tables for the authenticated property group. Tables are curated or filter-defined containers — not consent eligibility and not marketing segments. Requires scope read:tables.

Argument	Type	Description
`status`	string (optional)	`active` or `archived`.
`limit`	integer 1–500 (optional)	Page size.
`offset`	integer (optional)	Zero-based row offset.

table_get

Fetch one table by id, including member_count, last_refreshed_at, and latest_run_status. Requires scope read:tables.

Argument	Type	Description
`table_id`	string (required)	Table id.

table_members

Browse table members with offset pagination. A property pin narrows visible rows only. Requires scope read:tables.

Argument	Type	Description
`table_id`	string (required)	Table id.
`limit`	integer 1–500 (optional)	Page size.
`offset`	integer (optional)	Zero-based row offset.
`sort_by`	string (optional)	`entered_at`, `name`, `email`, `surname`, `first_name`.
`sort_dir`	string (optional)	`asc` or `desc`.

reviews_search

Search individual reviews by text, rating bounds, channel, date window, or host-response status — newest first. Requires scope read:reviews.

Argument	Type	Description
`q`	string (optional)	Free-text match on title, body, or guest name.
`min_rating` / `max_rating`	number (optional)	Rating bounds.
`channel`	string (optional)	Channel name.
`start_date` / `end_date`	ISO date (optional)	Review-date window.
`host_response`	boolean (optional)	Only reviews with/without a host response.
`limit`	integer 1–500 (optional)	Page size.
`cursor`	string (optional)	Pagination token from a previous `next_cursor`.

A tool call made without the required scope returns an MCP tool error (forbidden: missing scope <scope>) rather than failing the connection.

Connect

Claude (OAuth)

In Claude, add a custom connector and paste the MCP URL — no API key needed:

Settings → Connectors → Add custom connector.
Set the URL to https://api.casa-layer.com/mcp and add it.
Claude discovers the authorization server, opens WorkOS AuthKit, and you sign in and consent. If you belong to more than one organization, pick the one to connect at sign-in — the connection is locked to that org (to switch, remove and re-add the connector).
The connector now calls the read tools as you, scoped to your organization.

The connection is read-only and group-scoped: connector tokens can call the MCP read tools but are rejected on the REST API, and property drill-down (X-Property-Id) is not available over OAuth. Use an API key if you need property-pinned or REST access.

If the connector can’t complete sign-in, the most common cause is a server-side configuration gap (the MCP resource URL must be registered with WorkOS exactly as deployed). Cursor and the Inspector use the API-key path below and are unaffected.

Cursor (API key)

Most desktop MCP clients speak stdio, so bridge to the HTTP server with mcp-remote:

{
  "mcpServers": {
    "casa": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.casa-layer.com/mcp",
        "--header",
        "Authorization: Bearer ${CASA_API_KEY}"
      ],
      "env": { "CASA_API_KEY": "casa_your_key_here" }
    }
  }
}

MCP Inspector

Point the Inspector at the URL with Streamable HTTP transport and add an Authorization header:

npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP
# URL:       https://api.casa-layer.com/mcp
# Header:    Authorization: Bearer casa_your_key_here

Programmatic (TypeScript SDK)

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://api.casa-layer.com/mcp"),
  { requestInit: { headers: { Authorization: `Bearer ${process.env.CASA_API_KEY}` } } },
);

const client = new Client({ name: "my-app", version: "1.0.0" });
await client.connect(transport);

const result = await client.callTool({
  name: "master_profile_search",
  arguments: { q: "ada lovelace", limit: 10 },
});

Get started

Authentication

Data model

AI

MCP Server

Endpoint

Tools

Connect

Claude (OAuth)

Cursor (API key)

MCP Inspector

Programmatic (TypeScript SDK)

​Endpoint

​Tools

​Connect

​Claude (OAuth)

​Cursor (API key)

​MCP Inspector

​Programmatic (TypeScript SDK)

Endpoint

Tools

Connect

Claude (OAuth)

Cursor (API key)

MCP Inspector

Programmatic (TypeScript SDK)