MCP Server (AI Agents)

RedeCasas MCP Server

The mcp-worker (mcp.redecasas.com.br) exposes the RedeCasas APIs as MCP tools so an AI assistant can act on the user’s behalf: register the account, fill in their information, upload property photos, publish listings for sale or rent, register the CRECI profile and hand the human a Stripe checkout link.

Endpoint: https://mcp.redecasas.com.br/mcp (POST only)
Transport: Streamable HTTP, stateless (JSON responses; no mcp-session-id; GET/DELETE /mcp return 405 by spec design)
Protocol version: 2025-06-18
Discovery: https://mcp.redecasas.com.br/.well-known/mcp.json · landing card https://mcp.redecasas.com.br/
Local dev: http://localhost:8792/mcp (or through the dev proxy at http://localhost:3000/api/mcp)

Authentication (session-token tools)

No OAuth. The tools register_user and login return a session_token — the same 7-day session the website uses (shared KV session:{token}). Every write tool takes session_token as an explicit parameter. The worker validates the token against the shared D1/KV bindings before proxying. Expired tokens produce a readable error instructing the agent to log in again. logout invalidates the token.

Architecture

The worker is a translating proxy: MCP in, REST out. It fetches the backing workers over HTTPS (AUTH_API_BASE, LISTINGS_API_BASE, CORRETORES_API_BASE, BILLING_API_BASE, CHAT_API_BASE — configurable in .dev.vars for local dev). All validation, rate limits and business rules (the 1-free-listing gate, image magic-byte checks, CRECI approval flow) stay in the owning workers. The only direct D1 access is read-only: session validation and the search_listings tool. Admin endpoints are never exposed.

Credentials-bearing tools (register_user, login) are rate-limited at the MCP edge (10 / 15 min per IP, KV keys ratelimit:mcp:*); the original client IP is forwarded via X-Forwarded-For.

Tool catalog (23 tools)

Group	Tools	Auth
Conta	`register_user`, `login`, `logout`, `get_me`, `change_password`	token para `logout`/`get_me`/`change_password`
Imóveis	`create_listing`, `update_listing`, `set_listing_status`, `delete_listing`, `list_my_listings`, `get_listing`, `search_listings`, `upload_image_from_url`, `upload_image_base64`	token nas de escrita; `search_listings`/`get_listing` públicas
Corretores	`register_corretor`, `find_corretores`, `update_corretor_profile`, `delete_corretor_profile`	token nas de escrita
Cobrança	`get_subscription_status`, `create_checkout_url`, `get_billing_portal_url`	token
Conteúdo	`search_site`, `get_page_content`	pública

Facts agents must know (they are also in the tool descriptions):

Prices are integers in centavos (85000000 = R$ 850.000,00); rentals use the monthly value.
create_listing/update_listing accept listing_purpose: "venda" (default) or "aluguel" (D1 column listings.listing_purpose, migration 0012).
Photos are uploaded first (upload_image_from_url / upload_image_base64 → /api/listings/upload-image); JPEG/PNG/WebP/GIF, max 5 MB, min 200×200 px.
update_listing is partial at the MCP layer: the worker fetches the current listing and merges before the full-body REST PUT.
The 402 SUBSCRIPTION_REQUIRED error is rewritten to point the agent at create_checkout_url; payment is completed by the human in the browser.
Listing public URL: https://redecasas.com.br/imovel/?id={id}.

Connecting a client

# Claude Code / Claude Desktop
claude mcp add --transport http redecasas https://mcp.redecasas.com.br/mcp

// Cursor / Windsurf / Continue
{ "mcpServers": { "redecasas": { "url": "https://mcp.redecasas.com.br/mcp" } } }

A typical first conversation: “Cadastre a imobiliária do João (joão@…), publique o apartamento dele para alugar por R$ 2.500 em Florianópolis com essas fotos: …” — the assistant calls register_user → upload_image_from_url → create_listing (listing_purpose: "aluguel", price: 250000).

Operations runbook

cd mcp-worker
npm install          # hosts where sharp fails to build: npm install --ignore-scripts
npx tsc --noEmit     # typecheck
npm run dev          # local worker on :8792 (needs the other workers, see .dev.vars)
node ../scripts/mcp-smoke.mjs          # e2e smoke against :8792
node ../scripts/mcp-smoke.mjs --image foto.jpg   # full listing lifecycle incl. upload

Deploy: rides scripts/deploy-all.sh (typecheck loop → deploy_with_retry → health check https://mcp.redecasas.com.br/healthz). CI typechecks and deploys it via .github/workflows/workers.yml.
Health: curl https://mcp.redecasas.com.br/healthz → {"status":"ok"}. Also scripts/health-check-workers.sh.
Quick probe: curl -s https://mcp.redecasas.com.br/ shows the server card; POST /mcp with an initialize request should return server info.
DNS: mcp.redecasas.com.br is a wrangler custom domain — the record is created automatically on first deploy (needs the Cloudflare token to have DNS edit on the zone).
Rollback: cd mcp-worker && npx wrangler deployments list && npx wrangler rollback <deployment-id>.
Kill switch: the MCP worker only proxies; disabling it (wrangler delete or removing the route) never affects the site or the REST APIs.

Fast-follows (out of scope for v1)

OAuth 2.1 layer for MCP transport auth (unlocks ChatGPT Connectors).
MCP directory listings (smithery, glama, pulseMCP) — manual submissions.
Service bindings instead of public-URL fetches.