Agent Skills / maison-integrations

Install this skill alone, or read it below. Raw file: SKILL.md · references/tools.md

bash

npx skills add https://docs.maison-labs.com --skill maison-integrations

Maison — Integrations (PMS, payments, events)

Connect third-party systems to a hotel in one call: browse the provider catalogue, list a hotel's integrations (credentials masked), add or update an integration with credentials, config and tool audiences, enable, disable or remove it, verify a config value against the provider, list provider properties (rezStream, Mews, ResNexus), email a hotel's account holder the consent link for rezStream or STS Cloud, and list the PMS rate plans. Use when onboarding a hotel's PMS, payment gateway or booking system, or when a booking tool stops working.

Part of the Maison public API. Read the maison-public-api skill first for authentication, discovery and transport details (https://docs.maison-labs.com/skills/maison-public-api/SKILL.md).

When to use

Find the right provider and its required fields — list_integration_catalog.
Connect or update — add_integration (idempotent upsert).
Check why a provider call fails — check_integration_config, list_integration_properties.
Connect rezStream or STS Cloud — add_integration with the account holder's emailId, then send_integration_connect_link.
Pick a rate plan for a booking link or offer — list_pms_rate_plans.

Before you start

Send x-api-key: <key> on every call; the key only reaches /api/v1.
GET /api/v1/tools (or MCP tools/list) returns the tools THIS key may run — if a tool below is missing there, you lack a grant; do not retry it.
Client-scoped tools take clientId (a hotel id). whoami lists the ids you can act on.

Tools

Tool	What it does	REST	Needs
`add_integration`	Create or update a hotel's integration: creates a new integration row for the provider, or replaces an existing one's credentials, config, and tool audiences.	`PUT /api/v1/client/{clientId}/integration/{provider}`	update-client WRITE (client); plan: `update-client`
`check_integration_config`	Validates one operator-entered config value against the provider before it can silently break a guest conversation.	`GET /api/v1/client/{clientId}/integration/{provider}/configcheck`	update-client READ (client); plan: `update-client`; read-only
`disable_integration`	Pauses an integration — config and credentials are preserved but the integration is excluded from tool delivery at once, until re-enabled.	`POST /api/v1/client/{clientId}/integration/{provider}/disable`	update-client WRITE (client); plan: `update-client`; destructive
`enable_integration`	Re-enables a previously disabled integration — credentials and config are restored exactly as they were and its tools are served again at once.	`POST /api/v1/client/{clientId}/integration/{provider}/enable`	update-client WRITE (client); plan: `update-client`
`list_client_integrations`	Returns all active integrations for a hotel with credentials MASKED (last 4 characters only — never decrypted).	`GET /api/v1/client/{clientId}/integrations`	update-client READ (client); plan: `update-client`; read-only
`list_integration_catalog`	Returns the full integration provider catalog grouped by type (pms, bookingengine, payments, …), including credential/config fields and available tools for each provider, plus announced coming-soon placeholders.	`GET /api/v1/integrations/catalog`	clients READ (any); read-only
`list_integration_properties`	Returns the properties (rezStream), bookable services (Mews) or businesses (ResNexus) of the connected account, as `properties: [{ id, name, timezone, currency, address, bookablePeriod?	`GET /api/v1/client/{clientId}/integration/{provider}/properties`	update-client READ (client); plan: `update-client`; read-only
`list_pms_rate_plans`	Returns the rate plans of the hotel's connected PMS (the provider's own response shape), e.g.	`GET /api/v1/client/{clientId}/pms/rateplans`	hotel-config READ (client); plan: `hotel-config`; read-only
`remove_integration`	Soft-deletes the active integration row and wipes all stored credentials and tokens; for `stripe` it also deletes the hotel's Stripe webhook endpoint (best-effort).	`DELETE /api/v1/client/{clientId}/integration/{provider}`	update-client WRITE (client); plan: `update-client`; destructive
`send_integration_connect_link`	Emails the hotel's own account holder a one-time link to grant Maison access to their rezStream or STS Cloud account — the only way these integrations connect, because consent must come from the hotel.	`POST /api/v1/client/{clientId}/integration/{provider}/connectlink`	update-client EXECUTE (client); plan: `update-client`

Full input fields for every tool: references/tools.md.

Recommended workflows

Connect a PMS

list_integration_catalog → read the provider's credentialFields, configFields and tools.
add_integration with credentials and config exactly as the catalogue names them; set toolAudiences to control which tools guests may use.
For rezStream / STS Cloud: send_integration_connect_link; the hotel's account holder approves in their browser and the integration turns Connected (poll list_client_integrations).
list_integration_properties (rezstream/mews/resnexus) to pick the property/service/business id when the provider has several; it also refreshes the stored name of the selected one. Mews: refresh: true re-syncs the booking-engine configuration.
check_integration_config for fields the catalogue marks as verifiable, then enable_integration.

Tips

Only one PMS-type integration may be active per hotel; add_integration answers 409 when another is active.
Credentials are never returned; list_client_integrations shows masked values and connection state.
Stripe: add_integration with credentials.secretKey creates the hotel's Stripe webhook endpoint in the same call; a refused key is 422 stripe_key_invalid and nothing is saved. remove_integration deletes the endpoint.
disable_integration / enable_integration take effect at once on the instance that served the call; others follow within a minute.

Pitfalls

rezStream and STS Cloud connect only when the hotel's own account holder approves: send_integration_connect_link emails them (409 until emailId — and for STS Cloud the OAuth Client Secret — is saved; 503 where the flow is not configured). Each call issues a new link.
Never log or echo credentials back to the user.

Calling conventions

Same tool, three transports — pick whichever your runtime already speaks. Always send x-api-key.

bash

# REST
curl -X PUT "https://maison-labs.com/api/v1/client/<clientId>/integration/<provider>" -H "x-api-key: $MAISON_API_KEY" -H "content-type: application/json" -d '{}'

json

// MCP (https://maison-labs.com/mcp, Streamable HTTP): tools/call
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "add_integration", "arguments": {} } }

json

// A2A (https://maison-labs.com/a2a): tasks/send with a data part
{ "jsonrpc": "2.0", "id": 1, "method": "tasks/send", "params": { "message": { "role": "user", "parts": [{ "type": "data", "data": { "tool": "add_integration", "input": {} } }] } } }

Errors are the same everywhere: 401 no/invalid key; 403 forbidden with details.missing (the grants you lack — fall back to the composite's parts or stop); 403 not_entitled (the hotel's plan lacks the feature); 404, 409, 413 too_large, 503. Inputs that fail validation return 400 invalid_input with the Zod issues — fix and retry once.