Agent Skills / maison-account

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

Maison — Account and discovery

Discover what the calling API key may do before planning anything: who the key belongs to, whether they are Maison staff, every feature grant they hold globally or per hotel, and which hotel ids they can act on; and manage the caller's own API keys and connected apps. Use at the start of any session with the Maison public API, when a call returned 403, or when choosing which hotel id to pass. Also read or clear your own operator notices (agent replies, guest messages in conversations you handle, conversations needing attention, agent notices).

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

First call of a session: learn the user, grants and reachable client ids.
After a 403: compare details.missing with the grants whoami reports.
To choose a clientId for client-scoped tools when the user did not name one.
Catch up on what needs you — get_notice_summary, list_notices, then mark_notices_read (by ids, subject or category).
Review or stop your own access — list_my_api_keys / disable_my_api_key, list_my_connected_apps / revoke_my_connected_app (no grant needed; they only ever act on you).

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
`disable_my_api_key`	Disable one of your own API keys (an id from `list_my_api_keys`); calls with it are refused at once — including this call's key if you name it.	`DELETE /api/v1/me/apikey/{keyId}`	a valid API key; destructive
`get_notice_summary`	Your unread operator notices by category, across every hotel you can read conversations of: agent replies (your Maison agent sessions), guest messages (conversations you are handling, with message and conversation counts), conversations needing attention, and agent notices (notify_operator actions), each with per-hotel counts, plus `total`.	`GET /api/v1/notices/summary`	chat-logs READ (any); read-only
`list_my_api_keys`	Your own API keys, masked (prefix and last 4 characters — never the key itself), each with its description, creation, last use and whether it is disabled.	`GET /api/v1/me/apikeys`	a valid API key; read-only
`list_my_connected_apps`	The apps you have connected to your Maison account with OAuth (your active consents): each with the app, the scopes you granted (grouped by area), the hotels it may act on (`all` or a list), when you granted it and when it was last used.	`GET /api/v1/me/connectedapps`	a valid API key; read-only
`list_notices`	Your unread operator notices, newest first: id, category, tone, summary, subject (an agent session, a conversation or an agent execution), hotel, count and times, plus `subjectTitle` (an agent session's title, null otherwise) and `clientName` (the hotel's name, null without one).	`GET /api/v1/notices`	chat-logs READ (any); read-only
`mark_notices_read`	Mark your unread operator notices read.	`POST /api/v1/notices/read`	chat-logs READ (any)
`revoke_my_connected_app`	Revoke one of your own OAuth consents (a grant id from `list_my_connected_apps`): the app's access tokens are refused within 30 seconds and it cannot refresh; connecting again asks for consent again.	`POST /api/v1/me/connectedapp/{grantId}/revoke`	a valid API key; destructive
`whoami`	The user behind the API key, whether they are Maison staff, every feature grant they hold (global or per client) and the client ids they can act on.	`GET /api/v1/me`	a valid API key; read-only

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

Recommended workflows

Start a session

Call whoami (GET /api/v1/me). Note isMaisonAdmin, grants[] and clientIds[].
Call GET /api/v1/tools to see the catalogue filtered to this key — every tool listed is executable somewhere; client-scoped ones still need a permitted clientId.
If exactly one client id is reachable, use it by default; otherwise ask the user which hotel.

Tips

grants[].global is null for a feature the user holds only on specific clients; clients maps client id → level.
A level of EXECUTE implies WRITE implies READ.

Pitfalls

Do not infer permissions from a tool being present in the OpenAPI document — the document is public and lists everything; only GET /api/v1/tools is filtered.
disable_my_api_key on the key you are calling with stops this session's key at once — use another credential to continue.

Calling conventions

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

bash

# REST
curl -X DELETE "https://maison-labs.com/api/v1/me/apikey/<keyId>" -H "x-api-key: $MAISON_API_KEY"

json

// MCP (https://maison-labs.com/mcp, Streamable HTTP): tools/call
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "disable_my_api_key", "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": "disable_my_api_key", "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.