# Headout — how to use (mcp.ai)

Connect your Headout account and use 8 tools for scheduling and booking straight from your AI agent. Connect with your own API key. Headout is a travel experiences and activities booking platform offering tours, attractions, and entertainment bookings worldwide.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_headout?ms=1787293440000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `headout_get_product_by_id`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/headout`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/headout/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/headout/get/product/by/id` — Tool to retrieve detailed product information by product ID. Use when you need comprehensive product details including pricing, images, location, variants, and availability.
  - body: { language?: string, product_id: string, currencyCode?: string, fetch-variants?: boolean }
- `POST https://api.mcp.ai/api/headout/list/categories/v2` — Tool to fetch all available activity categories for a specific city using V2 API. Use when you need to list categories of activities available in a particular city location.
  - body: { cityCode: string, languageCode?: string }
- `POST https://api.mcp.ai/api/headout/list/cities` — Tool to list all active cities with pagination support. Use when you need to retrieve available cities from the Headout platform. Supports pagination through offset and limit parameters.
  - body: { limit?: integer, offset?: string }
- `POST https://api.mcp.ai/api/headout/list/collections/v2` — Tool to fetch all collections for a specific city using V2 API with pagination support. Use when you need to browse collections available in a particular city, with optional language-specific content 
  - body: { limit?: integer, offset?: integer, cityCode: string, languageCode?: string }
- `POST https://api.mcp.ai/api/headout/list/inventory/by/variant` — Tool to retrieve available inventory and pricing for a specific product variant. Use when you need to check availability and pricing details for booking.
  - body: { limit?: integer, offset?: string, variantId: string, endDateTime?: string, currencyCode?: string, startDateTime?: string }
- `POST https://api.mcp.ai/api/headout/list/products/by/category` — Tool to list product listings filtered by category ID with pagination support. Use when you need to retrieve products for a specific category.
  - body: { limit?: integer, offset?: string, language?: string, categoryId: string, currencyCode?: string }
- `POST https://api.mcp.ai/api/headout/list/products/v2` — Tool to fetch products using Headout V2 API with filtering by city, collection, category, or subcategory. Use when you need to retrieve product listings for specific locations or categories with pagin
  - body: { limit?: integer, offset?: integer, cityCode: string, categoryId?: string, campaignName?: string, collectionId?: string, currencyCode?: string, languageCode?: string, subCategoryId?: string }
- `POST https://api.mcp.ai/api/headout/list/subcategories/v2` — Tool to fetch all subcategories for a specific city using V2 API. Use when you need to list subcategories of activities available in a particular city location.
  - body: { cityCode: string, languageCode?: string }

## Example prompts
- "What can I do in Headout?"
- "Show me a summary of my Headout account"

## More
- Page: https://mcp.ai/headout
- Agent spec (llms.txt): https://mcp.ai/headout/llms.txt
- Postman collection: https://mcp.ai/headout/postman.json