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.
Connection
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 requiredSearch 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
ReadAvailabilityReturns 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 tokens onlySubmits 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
ReadBookingsLists 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.
| 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
ReadReviewsReturns published reviews for a community, sorted newest first. Community-bound tokens 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) |
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.
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.
-
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.
-
Sign in and authorize
The platform launches an OAuth request to hoastnow. Log in with your hoastnow account and approve the connection.
-
Start using hoastnow tools
Enable the connector in your conversation and ask your AI to search communities, check availability, or manage bookings.
https://www.hoastnow.com/mcpIDE & 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 mcp add hoastnow --transport http https://www.hoastnow.com/mcp. Then enter /mcp in your terminal, select hoastnow and authenticate.
mcp-remote bridge (see Advanced: Local Clients below).
codex mcp add hoastnow --url https://www.hoastnow.com/mcp. Then enter /mcp in your terminal and select hoastnow.
https://www.hoastnow.com/mcp, and complete OAuth when prompted.
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\):
{
"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:
{
"mcpServers": {
"hoastnow": {
"url": "https://www.hoastnow.com/mcp"
}
}
}/.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.
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);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 |