MCP Integration

Model Context Protocol (MCP) lets AI agents use Maison as a tool provider. Once configured, your agent can manage hotels, knowledge, users, integrations, and more — all without leaving your editor or chat interface.

This is the operator MCP server: it needs a Maison API key or an OAuth connection and acts with your account's permissions. Never connect it to an agent that serves hotel guests. For guest-facing agents, use the guest connector, which needs no key.

Endpoint

The MCP server uses Streamable HTTP transport at:

text

https://maison-labs.com/mcp

Authenticate every request with x-api-key: mx_p_YOUR_KEY. Session cookies are not accepted on this mount. The server builds a filtered tool set for the authenticated principal — tools/list only shows tools the key's user can execute somewhere.

Clients that support MCP sign-in (Claude, ChatGPT, Claude Code) need no key: add the URL with no headers and approve the connection in your browser. See Connect with OAuth.

Session lifecycle

http

# 1. Initialize — no mcp-session-id header yet
POST /mcp
Content-Type: application/json
Accept: application/json, text/event-stream
x-api-key: mx_p_YOUR_KEY
  →  200  +  mcp-session-id: <id>

# 2. Confirm initialization
POST /mcp
Mcp-Session-Id: <id>
  →  { method: "notifications/initialized" }

# 3. List tools (filtered to this key)
POST /mcp  (Mcp-Session-Id: <id>)
  →  tools/list response

# 4. Call a tool
POST /mcp  (Mcp-Session-Id: <id>)
  →  tools/call response

# 5. Open SSE stream (server-to-client notifications)
GET  /mcp  (Mcp-Session-Id: <id>)
  →  text/event-stream

# 6. Close the session
DELETE /mcp  (Mcp-Session-Id: <id>)
  →  200

Tool results

Every tool call returns the same shape regardless of success or failure:

Success

json

{
  "content": [{ "type": "text", "text": "<JSON output>" }],
  "structuredContent": { /* same object; scalars wrapped as { result } */ }
}

Failure

json

{
  "isError": true,
  "content": [{ "type": "text", "text": "forbidden: Missing grant clients WRITE" }],
  "structuredContent": {
    "error": "Forbidden",
    "code": "forbidden",
    "details": { "missing": [{ "feature": "clients", "level": "WRITE", "scope": "global" }] }
  }
}

Annotations on each tool mirror its definition: readOnlyHint, destructiveHint, idempotentHint.

Client configuration

Select your AI client below for exact configuration instructions. Every example connects to the same Maison MCP endpoint — just replace mx_p_YOUR_KEY with your actual API key.

Claude Desktop

Claude Desktop has native MCP support. Add the server to your claude_desktop_config.json file.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

json

{
  "mcpServers": {
    "maison": {
      "type": "http",
      "url": "https://maison-labs.com/mcp",
      "headers": { "x-api-key": "mx_p_YOUR_KEY" }
    }
  }
}

After saving, restart Claude Desktop. The Maison tools appear in the tool list when you start a new conversation.

MCP Quickstart for Users ↗

Claude Code (CLI)

Claude Code supports MCP via the claude mcp add CLI command or by editing .mcp.json directly. Use --scope to control where the config is stored.

Project: .mcp.json (in project root) User: ~/.claude.json (global)

bash

# Add via CLI (recommended)
claude mcp add maison \
  --transport http \
  --url https://maison-labs.com/mcp \
  --header "x-api-key: mx_p_YOUR_KEY"

# Or add to .mcp.json directly:
# {
#   "mcpServers": {
#     "maison": {
#       "type": "http",
#       "url": "https://maison-labs.com/mcp",
#       "headers": { "x-api-key": "mx_p_YOUR_KEY" }
#     }
#   }
# }

Use --scope project to share with your team via .mcp.json, or --scope user for personal use across all projects. Run /mcp inside Claude Code to check server status.

Claude Code MCP Docs ↗

VS Code (GitHub Copilot)

VS Code supports MCP servers through GitHub Copilot Chat. Create a .vscode/mcp.json file in your workspace, or use the MCP: Open User Configuration command for global config.

Workspace: .vscode/mcp.json User: Run 'MCP: Open User Configuration' from command palette

json

{
  "servers": {
    "maison": {
      "type": "http",
      "url": "https://maison-labs.com/mcp",
      "headers": {
        "x-api-key": "mx_p_YOUR_KEY"
      }
    }
  }
}

VS Code uses servers (not mcpServers) as the top-level key. Enable chat.mcp.discovery.enabled in settings to auto-discover servers from Claude Desktop and other clients.

VS Code MCP Docs ↗

Cursor

Cursor has built-in MCP support. Create a .cursor/mcp.json in your project for project-specific tools, or ~/.cursor/mcp.json for global availability.

Project: .cursor/mcp.json Global: ~/.cursor/mcp.json

json

{
  "mcpServers": {
    "maison": {
      "url": "https://maison-labs.com/mcp",
      "headers": {
        "x-api-key": "mx_p_YOUR_KEY"
      }
    }
  }
}

The Composer Agent automatically uses MCP tools when relevant. You can also configure via Settings > MCP in the Cursor UI. By default, Cursor asks for approval before using MCP tools — enable auto-run to skip the prompt.

Cursor MCP Docs ↗

Windsurf (Codeium)

Windsurf connects MCP servers through its Cascade AI agent. Configure via the MCP Marketplace in the Cascade panel or by editing the config file directly.

macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

json

{
  "mcpServers": {
    "maison": {
      "serverUrl": "https://maison-labs.com/mcp",
      "headers": {
        "x-api-key": "mx_p_YOUR_KEY"
      }
    }
  }
}

Windsurf uses serverUrl for remote HTTP servers (not url). Environment variable interpolation is supported with ${env:API_KEY} syntax.

Windsurf MCP Docs ↗

Gemini CLI

Gemini CLI stores MCP configuration in settings.json. Project-level settings take precedence over global settings.

Global: ~/.gemini/settings.json Project: .gemini/settings.json

json

{
  "mcpServers": {
    "maison": {
      "httpUrl": "https://maison-labs.com/mcp",
      "headers": {
        "x-api-key": "mx_p_YOUR_KEY"
      },
      "timeout": 30000
    }
  }
}

Gemini CLI supports command (stdio), url (SSE), and httpUrl (Streamable HTTP) transports. Use httpUrl for Maison. Environment variables in the env block expand automatically with $VAR syntax. Optional: set "trust": true to bypass tool confirmation prompts.

Gemini CLI MCP Docs ↗

ChatGPT

ChatGPT supports MCP via the web UI, desktop app, and the Responses API. Available for Pro, Team, Enterprise, and Edu users with Developer Mode enabled.

Settings > Apps (formerly Connectors) > Add source

json

// Via the Responses API:
{
  "model": "gpt-4o",
  "input": [{ "role": "user", "content": "List my clients" }],
  "tools": [
    {
      "type": "mcp",
      "server_label": "maison",
      "server_url": "https://maison-labs.com/mcp",
      "headers": { "x-api-key": "mx_p_YOUR_KEY" },
      "require_approval": "never"
    }
  ]
}

UI setup: Open ChatGPT > Settings > Apps > Advanced settings > enable Developer Mode. Then in any chat, click + > More > Developer Mode > Add sources and enter https://maison-labs.com/mcp. ChatGPT currently uses SSE transport for MCP connections.

OpenAI MCP Docs ↗

JetBrains IDEs (IntelliJ, WebStorm, PyCharm)

JetBrains IDEs support MCP through AI Assistant. Configure via Settings > Tools > AI Assistant > Model Context Protocol (MCP), or edit the config file directly.

Settings > Tools > AI Assistant > MCP > Add Or: project-level .idea/mcp.json

json

{
  "mcpServers": {
    "maison": {
      "url": "https://maison-labs.com/mcp",
      "headers": {
        "x-api-key": "mx_p_YOUR_KEY"
      }
    }
  }
}

For HTTP remote servers, only the url field is required. You can also use the MCP Installation Assistant (available in newer JetBrains builds) to add servers interactively. The Junie CLI agent supports MCP configuration via junie mcp add.

JetBrains MCP Docs ↗

Tool catalogue

The following tools are available on the MCP server. The catalogue is rendered live from https://maison-labs.com/api/v1/openapi.json. Use tools/list to see only the tools your key can execute.

Loading catalogue…

Troubleshooting

401 Unauthorized

The x-api-key header is missing or the key value is invalid. Session cookies are not accepted on this mount. Verify your key with curl https://maison-labs.com/api/v1/me -H "x-api-key: mx_p_YOUR_KEY".

404 Session not found

The mcp-session-id is unknown or has expired. Re-run initialize to start a new session.

Tool missing from tools/list

The key's user lacks one of the tool's grants on every client they have access to. Call GET https://maison-labs.com/api/v1/tools/<name> to see which grant is missing.

forbidden on call but tool is listed

The grant exists for a different client. The input's clientId is not covered by the key's permissions.

Never commit your API key to source control. Use environment variables or your client's secret management features. Most clients support variable interpolation in config files.