Maison — Feature plans and entitlements (Maison staff)

Control what a hotel's plan includes: read the caller's per-feature access snapshot for a hotel, list and change the hotel's entitled features (grant/revoke in one call), push a feature to every child property, and manage plan templates (create, update, assign, apply with optional pruning, drift report, per-client overrides, plan history), Maison's payment gateway fees and the feature catalogue. Each plan feature is on or locked (shown to the hotel locked, with the plan's message); a feature left out is off. Use when a hotel upgrades or downgrades, when a tool answers 403 not_entitled, or when standardising plans across a group.

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

• A tool returned not_entitled — get_client_access shows what the plan lacks; set_client_features fixes it.
• Roll out a plan — set_client_plan (assign + apply) or apply_plan_template.
• Who changed a plan and when — list_plan_template_history / list_client_plan_history.
• Invoice hotels for payments — get_gateway_fee_totals with from/to (optionally clientId).

Before you start

1. Send x-api-key: <key> on every call; the key only reaches /api/v1.
2. 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.
3. Client-scoped tools take clientId (a hotel id). whoami lists the ids you can act on.

Tools

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

Recommended workflows

Upgrade a hotel to a plan template

1. list_plan_templates → pick the template id.
2. set_client_plan with templateId and prune: false (keeps extra grants) or true (exact match).
3. get_client_plan to review drift afterwards.

Give one hotel an exception to its plan

1. set_client_feature_override with state "on", "off" or "locked" — it wins over the plan and the hotel's features are reconciled at once.
2. clear_client_feature_override returns the feature to the plan default.
3. get_client_plan lists the hotel's overrides and its locked features.

Tips

• get_client_access is the fastest way to answer 'what can I do for this hotel?' — it merges plan entitlement with the caller's grants.
• Plan history pages by offset (limit, offset) and returns total.
• Gateway fees: a client's own fee wins over its plan's fee (source says which applies); setting and clearing fees is Maison staff only (global clients WRITE).
• create_feature / update_feature / deprecate_feature change the platform feature catalogue (global maison-roles WRITE) — prefer an existing feature.

Pitfalls

• All plan tools except get_client_access need the GLOBAL client-feature-management grant (Maison staff).
• apply_plan_template with prune: true revokes features not in the template — confirm with the user first.
• A Maison-only feature cannot be locked (400) — use off instead.
• delete_plan_template answers 409 while any hotel is on the plan — list_plan_template_clients lists them; move them to another plan first.

Calling conventions

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

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

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

// 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": "apply_plan_template", "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.