---
name: "maison-platform"
description: "Orient and verify: the documentation index with machine-readable discovery URLs, the exact widget embed code for a hotel, a website check (framework, widget present, client id), the AI site diagnostic (start, read findings, ask follow-ups) and a live platform health summary. Use when installing the widget on a hotel's site, when a site seems not to load the concierge, or to find the right documentation page. Tools: chat_site_diagnostic, check_website, get_documentation, get_platform_status, get_site_diagnostic, get_widget_embed_code, start_site_diagnostic."
license: "Proprietary. Use with a Maison API key under the Maison terms of service."
metadata:
  author: "maison-labs"
  version: "1.0.0"
  category: "platform"
  api-base: "https://maison-labs.com"
  openapi: "https://maison-labs.com/api/v1/openapi.json"
  docs: "https://docs.maison-labs.com/skills/maison-platform/"
---

# Maison — Platform, documentation and diagnostics

Orient and verify: the documentation index with machine-readable discovery URLs, the exact widget embed code for a hotel, a website check (framework, widget present, client id), the AI site diagnostic (start, read findings, ask follow-ups) and a live platform health summary. Use when installing the widget on a hotel's site, when a site seems not to load the concierge, or to find the right documentation page.

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

- Install the widget — `get_widget_embed_code`, then `check_website` to verify.
- A hotel site misbehaves — `start_site_diagnostic` → `get_site_diagnostic` → `chat_site_diagnostic`.
- Find documentation — `get_documentation`.

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

| Tool | What it does | REST | Needs |
| --- | --- | --- | --- |
| `chat_site_diagnostic` | Send a follow-up question about a finished or running diagnostic session and get the agent's answer. | `POST /api/v1/diagnostic/{sessionId}/chat` | a valid API key |
| `check_website` | Fetch a public website and report its framework, whether the Maison widget loader is embedded and which client id it carries. | `POST /api/v1/tools/sitecheck` | a valid API key; read-only |
| `get_documentation` | Where the public documentation lives: the docs site topics (quick start, authentication, API reference, MCP, A2A, widget SDK, installation guides, integrations, diagnostic), plus the machine-readable discovery URLs (OpenAPI document, agent card, filtered tool catalogue). | `GET /api/v1/docs` | a valid API key; read-only |
| `get_platform_status` | A live health summary from the API's point of view: environment, database reachability, LLM service reachability and the public status page URL. | `GET /api/v1/status` | a valid API key; read-only |
| `get_site_diagnostic` | The full history of a diagnostic session — run events, progress, findings and chat turns. | `GET /api/v1/diagnostic/{sessionId}` | a valid API key; read-only |
| `get_widget_embed_code` | The exact HTML a hotel pastes into its website to show the Maison chat widget: the hardened loader <script> tag for this environment's CDN and the `initMcbs` call with the hotel's client id. | `GET /api/v1/client/{clientId}/embed` | clients READ (client); read-only |
| `start_site_diagnostic` | Start the AI website diagnostic for a URL: it crawls the site, checks the widget, content and structure, and streams findings. | `POST /api/v1/diagnostic` | a valid API key |

Full input fields for every tool: [references/tools.md](references/tools.md).

## Recommended workflows

### Install and verify the widget

1. `get_widget_embed_code` for the hotel; give the operator the `html` block.
2. After they publish, `check_website` with the site URL: `hasAgentScript` and the detected client id confirm the install.
3. If something is off, `start_site_diagnostic` and read the findings.

## Tips

- `get_platform_status` is a quick way to tell an API outage from a hotel-specific problem.

## Pitfalls

- Diagnostics run against public URLs only; private or password-protected sites cannot be checked.

## Calling conventions

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

```bash
# REST
curl -X POST "https://maison-labs.com/api/v1/diagnostic/<sessionId>/chat" -H "x-api-key: $MAISON_API_KEY" -H "content-type: application/json" -d '{ "message": … }'
```

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

```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": "chat_site_diagnostic", "input": { "message": … } } }] } } }
```

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.