Developers
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. MCP requests are authenticated via OAuth 2.1. Clients can self-register via Dynamic Client Registration (RFC 7591) or the platform admin can issue a client manually. API keys are not supported on the MCP endpoint — use them with the REST API instead.

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. AI agents that support OAuth (Claude marketplace, Cursor MCP) can 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)

Connecting a Client

Any MCP-compatible client can connect to the OAuth-protected MCP endpoint. Here are configuration snippets for the most common environments.

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