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
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 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) |
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\):
{
"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 |