MCP Protocolo de contexto de modelo

Integração de agentes de IA

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.

Conexão

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

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.

Ferramentas disponíveis

Seis ferramentas são expostas. Cada uma aplica o mesmo escopo de tenant que a API REST — tokens de comunidade veem apenas seus próprios dados; tokens de marca veem apenas suas próprias reservas.

search_communities OAuth obrigatório (qualquer perfil autenticado)

Search active, approved communities by location or minimum capacity. Returns up to 50 results — the same approved catalog a logged-in user sees on /search. This tool runs only after OAuth and does not work anonymously. Useful for discovery workflows before checking specific space availability.

Parâmetro	Tipo	Obrigatório	Descrição
`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.

Parâmetro	Tipo	Obrigatório	Descrição
`spaceId`	integer	yes	ID of the space to check
`date`	string	yes	Date to check in YYYY-MM-DD format

create_booking_request WriteBookings Apenas tokens de marca

Submits a booking request on behalf of a brand. The request enters a Pending state until the community approves it. Pricing is the flat event fee plus the brand service fee from payment settings (duration does not change the fee).

Parâmetro	Tipo	Obrigatório	Descrição
`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 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.

Parâmetro	Tipo	Obrigatório	Descrição
`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-bound tokens can only access their own community's reviews.

Parâmetro	Tipo	Obrigatório	Descrição
`communityId`	integer	yes	ID of the community
`limit`	integer	no	Max results to return (default 20, max 100)

list_my_listings ReadAvailability tenant-bound

Community-scoped tokens get every community they manage plus spaces under each. Brand-scoped tokens get their brand profile plus campaigns. Tokens with no community or brand binding return an error.

Parâmetro	Tipo	Obrigatório	Descrição
None — this tool takes no parameters.

Conecte seu assistente de IA

A forma mais fácil de usar o hoastnow com IA é pelas configurações de conectores ou apps da sua plataforma — sem arquivos de configuração. Basta adicionar a URL MCP, fazer login no hoastnow e autorizar.

Recomendado

Conexão rápida pela web

Se você já tem uma conta hoastnow, conectar leva menos de um minuto. Sua plataforma de IA gerencia o OAuth automaticamente — basta fazer login e aprovar o acesso.

Adicione o hoastnow como conector ou app
Nas configurações da sua plataforma de IA, crie um novo conector MCP personalizado (ou app) e cole a URL do servidor abaixo.
Faça login e autorize
A plataforma inicia uma solicitação OAuth para o hoastnow. Faça login com sua conta hoastnow e aprove a conexão.
Comece a usar as ferramentas do hoastnow
Ative o conector na sua conversa e peça à sua IA para buscar comunidades, verificar disponibilidade ou gerenciar reservas.

URL do servidor MCP 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.

Pronto — sem API keys, sem arquivos JSON de configuração, sem configuração manual de cliente OAuth. Suas permissões seguem o papel da sua conta hoastnow (marca, comunidade, etc.) e você pode desconectar a qualquer momento nas configurações da sua plataforma de IA.

Avançado: clientes locais

Para IDEs de desktop e apps de IA locais que não têm interface de conector web, você pode conectar editando um arquivo JSON de configuração. Esses exigem mais configuração do que o fluxo de conector web acima.

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/mcp 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 API REST

Ambas as interfaces compartilham a mesma autenticação, permissões e dados. Escolha com base no seu caso de uso:

	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

OAuth 2.1 Reference Endpoints, scopes, PKCE, and token examples REST API Reference Full endpoint docs with request/response schemas