MCP Integration

Model Context Protocol (MCP) lets AI assistants use Maison as a tool provider. Once configured, your assistant can query the hotel concierge, manage sessions, and read client configuration — all without leaving your editor or chat interface.

Prerequisites

Before configuring any client, you need a Maison API key. See the Authentication page for how to create one. Your key will start with mx_p_. The MCP endpoint for all clients is:

text

https://maison-labs.com/mcp

Maison uses Streamable HTTP transport (the modern MCP standard). Most clients support this natively. For clients that only support stdio, use the @anthropic-ai/mcp-remote bridge package as shown in the Claude Desktop example below.

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 was the first MCP client and has native support built in. 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": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-remote", "https://maison-labs.com/mcp"],
      "env": {
        "API_KEY": "mx_p_YOUR_KEY"
      }
    }
  }
}

After saving, restart Claude Desktop. The Maison tools will 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": "Ask the hotel about checkout time" }],
  "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 ↗

Available Tools

The MCP server exposes five tools that your AI client can call. Each tool requires a clientId to identify the hotel property.

Tool	Description	Parameters
query_hotel	Ask the hotel concierge a question	clientId, query, sessionId?
get_session	Retrieve an existing chat session by ID	clientId, sessionId
create_session	Start a new chat session	clientId
get_client_info	Get client configuration and settings	clientId
list_translations	List available UI translations for a client	clientId

Available Resources

Three read-only resources are available for direct access. Use these to fetch configuration or session data without calling a tool.

Resource	URI Pattern	Description
Client config	maison://client/{clientId}/config	Property settings, features, and chat configuration
Translations	maison://client/{clientId}/translations	UI strings and label overrides for the chat widget
Session	maison://session/{clientId}/{sessionId}	Full message history for an existing chat session

Session Lifecycle

MCP uses Streamable HTTP transport. Sessions are established on the first request and identified by the mcp-session-id response header. Your client handles this automatically.

http

# Initialize — no session header required
POST /mcp  →  response includes mcp-session-id

# Subsequent tool calls — supply the session ID
POST /mcp  (Mcp-Session-Id: <id>)  →  call tools, list resources

# Server-sent event stream for notifications
GET  /mcp  (Mcp-Session-Id: <id>)  →  SSE stream

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

Troubleshooting

Connection refused or timeout

Verify your API key is valid by calling the auth check endpoint: curl https://maison-labs.com/auth/ -H "x-api-key: mx_p_YOUR_KEY". A 200 response confirms the key is active.

Tools not appearing

Most clients require a restart after adding an MCP server. In Claude Code, run /mcp to check status. In VS Code, open the Output panel and select "MCP" from the dropdown.

401 Unauthorized

Ensure your API key is passed correctly. Different clients use different field names: env.API_KEY (Claude Desktop), headers.x-api-key (VS Code, Cursor, Gemini), or headers (ChatGPT API). Check the examples above for your client.

stdio vs HTTP transport

Maison uses Streamable HTTP transport natively. If your client only supports stdio (e.g. Claude Desktop), use the @anthropic-ai/mcp-remote bridge as shown in the Claude Desktop config above. This runs a local proxy that translates between stdio and HTTP.

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.