MCP Model Context Protocol

AI Agent Integration

hoastnow exposes a native Model Context Protocol server so AI agents — Claude, Cursor, Copilot, and any MCP-compatible client — can search communities, check availability, and create bookings without screen-scraping or custom glue code. The same API key and permission model used by the REST API governs MCP access.

Connection

Endpoint https://app.hoastnow.com/mcp

Transport HTTP (Streamable HTTP)

Authentication Bearer token — same API key as the REST API

MCP keys use the same permission flags as the REST API. Issue your key from the API Keys page and grant the permissions the agent needs.

Available Tools

Five tools are exposed. Each tool enforces the same tenant scoping as the REST API — Community keys see only their own data; Brand keys see only their own bookings.

search_communities No auth required

Search active, approved communities by location or minimum capacity. Returns up to 50 results. Useful for discovery workflows before checking specific space availability.

Parameter	Type	Required	Description
`location`	string	no	Substring match against community address
`minCapacity`	integer	no	Minimum resident count
`date`	string	no	Reserved — YYYY-MM-DD format

check_availability ReadAvailability

Returns available hour-long time slots for a specific space on a given date, accounting for existing confirmed bookings.

Parameter	Type	Required	Description
`spaceId`	integer	yes	ID of the space to check
`date`	string	yes	Date to check in YYYY-MM-DD format

create_booking_request WriteBookings Brand keys only

Submits a booking request on behalf of a brand. The request enters a Pending state until the community approves it. Pricing is calculated automatically — subtotal plus a 10% service fee.

Parameter	Type	Required	Description
`spaceId`	integer	yes	ID of the space to book
`startTime`	string	yes	ISO 8601 datetime or `YYYY-MM-DD HH`
`message`	string	no	Optional note to the community

get_bookings ReadBookings

Lists bookings visible to the authenticated key. Returns up to 100 results, sorted newest first. Community keys see all bookings for their spaces; Brand keys see only their own bookings.

Parameter	Type	Required	Description
`status`	string	no	`Pending`, `Confirmed`, `Cancelled`, `Completed`, `Rejected`
`fromDate`	string	no	Start of date range (YYYY-MM-DD)
`toDate`	string	no	End of date range (YYYY-MM-DD)

get_community_reviews ReadReviews

Returns published reviews for a community, sorted newest first. Community-scoped keys can only access their own community's reviews.

Parameter	Type	Required	Description
`communityId`	integer	yes	ID of the community
`limit`	integer	no	Max results to return (default 20, max 100)

Connecting a Client

Any MCP-compatible client can connect using the endpoint and your API key. Here are configuration snippets for the most common environments.

Claude Desktop

Add hoastnow to your claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

claude_desktop_config.json

{
  "mcpServers": {
    "hoastnow": {
      "type": "http",
      "url": "https://app.hoastnow.com/mcp",
      "headers": {
        "Authorization": "Bearer hoa_live_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Cursor

Open Cursor Settings → MCP and add a new server, or edit .cursor/mcp.json in your project root:

.cursor/mcp.json

{
  "mcpServers": {
    "hoastnow": {
      "type": "http",
      "url": "https://app.hoastnow.com/mcp",
      "headers": {
        "Authorization": "Bearer hoa_live_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Programmatic (MCP SDK)

Connect from code using the official TypeScript or Python MCP SDK:

TypeScript

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({ name: "my-app", version: "1.0.0" });

await client.connect(
  new StreamableHTTPClientTransport(
    new URL("https://app.hoastnow.com/mcp"),
    { requestInit: { headers: { Authorization: "Bearer hoa_live_xxxxxxxxxxxxxxxxxxxx" } } }
  )
);

// Call a tool
const result = await client.callTool({
  name: "check_availability",
  arguments: { spaceId: 42, date: "2026-04-15" },
});
console.log(result.content);

Python

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async with streamablehttp_client(
    "https://app.hoastnow.com/mcp",
    headers={"Authorization": "Bearer hoa_live_xxxxxxxxxxxxxxxxxxxx"},
) as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()

        result = await session.call_tool(
            "check_availability",
            arguments={"spaceId": 42, "date": "2026-04-15"},
        )
        print(result.content)

MCP vs REST API

Both interfaces share the same authentication, permissions, and data. Choose based on your use case:

	MCP	REST API
Best for	AI agents, LLM-powered apps, chat interfaces	Backend services, dashboards, data pipelines
Discovery	Tools self-describe — agents learn capabilities automatically	Developer reads docs and writes calls explicitly
Webhooks	Not supported via MCP	Full webhook support
Auth	Same API key and permission flags for both

REST API Reference Full endpoint docs with request/response schemas Get API Keys Issue a key with the permissions you need