Developers
MCP Model Context Protocol

AI Agent Integration

hoastnow exposes a native Model Context Protocol server so AI assistants can search communities, check availability, and create bookings without screen-scraping or custom glue code. The fastest way to connect is through your AI platform's built-in connector or app settings — just add the MCP URL, sign in to your hoastnow account, and authorize. No JSON config files required. MCP requests are authenticated via OAuth 2.1; API keys are not supported on the MCP endpoint — use them with the REST API instead.

For most brands and community teams: the easiest experience is at hoastnow.com/ai — connect directly inside ChatGPT, Claude, Grok, or Gemini web. This page is the complete technical reference (tools, auth, Cursor/Claude Code, SDKs).

Connection

Endpoint https://www.hoastnow.com/mcp
Transport HTTP (Streamable HTTP)
Authentication OAuth 2.1 (Bearer JWT) — scope: hoastnow.mcp, resource: mcp
Discovery /.well-known/oauth-protected-resource
MCP requires an OAuth 2.1 access token bound to the mcp resource indicator and the hoastnow.mcp scope. Web connectors handle this automatically — when you add hoastnow as a connector, the platform opens an OAuth prompt so you can sign in and authorize. Clients can also self-register via Dynamic Client Registration; for a fixed integration, an admin can create a client from the Backoffice → OAuth Clients tab.

Available Tools

Five tools are exposed. Each tool enforces the same tenant scoping as the REST API — tokens issued to a community see only their own data; tokens issued to a brand 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.

ParameterTypeRequiredDescription
locationstringnoSubstring match against community address
minCapacityintegernoMinimum resident count
datestringnoReserved — 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.

ParameterTypeRequiredDescription
spaceIdintegeryesID of the space to check
datestringyesDate to check in YYYY-MM-DD format
create_booking_request WriteBookings Brand tokens 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.

ParameterTypeRequiredDescription
spaceIdintegeryesID of the space to book
startTimestringyesISO 8601 datetime or YYYY-MM-DD HH
messagestringnoOptional note to the community
get_bookings ReadBookings

Lists bookings visible to the authenticated token. Returns up to 100 results, sorted newest first. Community-bound tokens see all bookings for their spaces; brand-bound tokens see only their own bookings.

ParameterTypeRequiredDescription
statusstringnoPending, Confirmed, Cancelled, Completed, Rejected
fromDatestringnoStart of date range (YYYY-MM-DD)
toDatestringnoEnd of date range (YYYY-MM-DD)
get_community_reviews ReadReviews

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

ParameterTypeRequiredDescription
communityIdintegeryesID of the community
limitintegernoMax results to return (default 20, max 100)

Connect Your AI Assistant

The easiest way to use hoastnow with AI is through your platform's built-in connector or app settings — no config files needed. Just add the MCP URL, sign in to hoastnow, and authorize.

Recommended

Quick Connect via Web

If you already have a hoastnow account, connecting takes less than a minute. Your AI platform handles OAuth automatically — you just log in and approve access.

  1. Add hoastnow as a connector or app

    In your AI platform's settings, create a new custom MCP connector (or app) and paste the server URL below.

  2. Sign in and authorize

    The platform launches an OAuth request to hoastnow. Log in with your hoastnow account and approve the connection.

  3. Start using hoastnow tools

    Enable the connector in your conversation and ask your AI to search communities, check availability, or manage bookings.

MCP server URL https://www.hoastnow.com/mcp

IDE & Power User Integrations

Connect from Cursor, Claude Code, Codex, and desktop clients. For the simplest experience inside everyday web chats (ChatGPT, Claude, Grok, Gemini), visit hoastnow.com/ai.

Claude Code
Run this command in your terminal: claude mcp add hoastnow --transport http https://www.hoastnow.com/mcp. Then enter /mcp in your terminal, select hoastnow and authenticate.
Claude Desktop
Go to Settings → Connectors → Add custom connector and add the MCP link.
If your version does not support remote HTTP OAuth natively, use the mcp-remote bridge (see Advanced: Local Clients below).
ChatGPT
First, turn on Developer Mode. Then go to Settings → Apps → Create app and add the MCP link.
Developer mode is required (Settings → Apps → Advanced settings). Full write tools need Business/Enterprise/Edu plans.
Codex
Go to Settings → MCP servers → Streamable HTTP and add the MCP link.
Codex CLI
Run this command in your terminal: codex mcp add hoastnow --url https://www.hoastnow.com/mcp. Then enter /mcp in your terminal and select hoastnow.
Cursor
Give your agent the MCP link. Then go to Settings → Cursor Settings → Tools & MCPs → Connect.
Grok
Go to grok.com/connectors, click New Connector → Custom, paste https://www.hoastnow.com/mcp, and complete OAuth when prompted.
That's it — no API keys, no JSON config files, no manual OAuth client setup. Your permissions follow your hoastnow account role (brand, community, etc.), and you can disconnect anytime from your AI platform's settings.

Advanced: Local Clients

For desktop IDEs and local AI apps that don't have a web connector UI, you can connect by editing a JSON config file. These require more setup than the web connector flow above.

Claude Desktop

Claude Desktop currently doesn't have native OAuth for HTTP MCP servers. Use the mcp-remote bridge as an npx command in your claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

claude_desktop_config.json
{
  "mcpServers": {
    "hoastnow": {
      "command": "npx",
      "args": ["mcp-remote", "https://www.hoastnow.com/mcp"]
    }
  }
}
mcp-remote performs the OAuth handshake on Claude Desktop's behalf. The first time you connect, it opens your browser to grant consent.

Cursor

Cursor supports remote HTTP MCP with OAuth natively. Open Cursor Settings → MCP and add a new server, or edit .cursor/mcp.json in your project root:

.cursor/mcp.json
{
  "mcpServers": {
    "hoastnow": {
      "url": "https://www.hoastnow.com/mcp"
    }
  }
}
Cursor will discover the auth server via the /.well-known/oauth-protected-resource document and prompt you to authenticate the first time the server is used.

Programmatic (MCP SDK)

Connect from code using the official TypeScript or Python MCP SDK. Both SDKs ship with OAuth provider hooks — see the TypeScript SDK and Python SDK OAuth examples for full implementations. The simplified examples below assume your code has already obtained an access token via a separate OAuth library; the token must include the hoastnow.mcp scope and bind to resource=mcp.

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

// accessToken obtained via your OAuth client (PKCE auth-code or client_credentials),
// requested with scope=hoastnow.mcp and resource=mcp.
const accessToken = await getHoastnowMcpToken();

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

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

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

# access_token obtained via your OAuth client (PKCE auth-code or client_credentials),
# requested with scope=hoastnow.mcp and resource=mcp.
access_token = get_hoastnow_mcp_token()

async with streamablehttp_client(
    "https://www.hoastnow.com/mcp",
    headers={"Authorization": f"Bearer {access_token}"},
) 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 OAuth 2.1 only OAuth 2.1 or long-lived API key
Restoring connection…
Connection lost. Reload