AI_Calling — Retell HubSpot MCP Server

Middle layer between Retell AI (Cara), HubSpot Scheduler/CRM, and Supabase for tour availability, booking, and call logging.

Retell call → Render MCP server → HubSpot Scheduler API + CRM → Supabase logging

Architecture

HTTP routes

Related MCP server: HubSpot MCP Server

Local setup

1. Copy environment file:

   cp .env.example .env

2. Fill in .env with your real values (never commit .env).

3. Run Supabase SQL from supabase/schema.sql in the Supabase SQL editor.

4. Install and start:

   npm install
   npm run dev

5. Verify health:

   curl http://localhost:3000/health

Environment variables

Use these exact names locally (.env) and in Render (Dashboard → Web Service → Environment).

Where to get secrets

• HubSpot token: Settings → Integrations → Private Apps → Retell Connection → Access token

• Supabase service role: Supabase → Project Settings → API → service_role key

• MCP secret: Generate a long random string; use the same value in Retell MCP headers

Important: Do not use the Supabase publishable (anon) key for server-side inserts if RLS is enabled. Use the service role key in Render only — never expose it client-side or in Retell.

Important: Do not use the old Carabanchel_Direct_Booking_Integration HubSpot app. Use Retell Connection only.

HubSpot scopes required

The Retell Connection private app needs:

• crm.objects.contacts.write

• crm.objects.contacts.read

• crm.objects.deals.write

• crm.objects.deals.read

• crm.schemas.deals.read

• crm.objects.contacts.read (contact phone lookup during call sync)

• crm.schemas.contacts.read

• crm.objects.owners.read

• automation

• scheduler.meetings.meeting-link.read

• meetings-write ← required for booking; add before live booking tests

Render deployment

Do not use yarn or yarn start — this repo uses npm (package-lock.json). Using yarn alone skips the TypeScript build and can resolve incompatible dependency versions.

Recommended Render settings:

If Render still uses yarn for build, the app will start via tsx (commit 1a6921c+) but you should switch to npm for reliable installs. Node 22 is required (see .nvmrc).

Add all environment variables from the table above in Render → Environment.

After changing build/start commands in the Render dashboard, trigger Manual Deploy → Clear build cache & deploy.

Connect Retell MCP

In Retell → MCP → Add MCP:

Select these tools after deploy:

• get_tour_availability

• book_tour (requires HubSpot meetings-write scope)

• log_retell_session

• log_tour_preference

Optional webhook (post-call): POST https://ai-calling-j1hu.onrender.com/webhooks/retell with the same bearer header.

Cara prompt behavior

When the guest wants a tour:

1. Ask whether they prefer a virtual or in-person tour.

2. Ask which day works best.

3. Ask what Madrid time generally works best.

4. Call get_tour_availability.

5. Offer one or two available slots.

6. Ask clearly: "Should I book that for you?"

7. Only after the guest clearly confirms, call book_tour.

8. Do not say the tour is booked until book_tour returns success.

9. If booking fails, say: "No problem, I'll send you the tour links by WhatsApp so you can choose the time that works best for you."

10. Log the result with log_retell_session or log_tour_preference.

Manual test scripts

# Test HubSpot availability (requires HUBSPOT_ACCESS_TOKEN in .env)
npx tsx scripts/testAvailability.ts

# Test Supabase inserts (requires SUPABASE_* in .env)
npx tsx scripts/testSupabaseInsert.ts

# Test live booking (guarded — only runs when enabled)
RUN_BOOKING_TEST=true TEST_BOOKING_EMAIL=you@example.com npx tsx scripts/testBookTour.ts

Pre-live checklist

1. Run supabase/schema.sql in Supabase

2. Deploy to Render with all env vars

3. Confirm GET /health returns { "ok": true }

4. Run testAvailability.ts and testSupabaseInsert.ts

5. Connect Retell MCP with bearer auth

6. Test a call with your own HubSpot contact and phone

7. Add meetings-write scope if booking fails with missing scope errors

8. Only then enable for real leads

Supabase tables

• retell_sessions — Retell call/session metadata plus HubSpot deal/contact enrichment (upsert by session_id)

• mcp_tool_calls — MCP tool request/response logs

• tour_bookings — Tour bookings and preferences

• sync_runs — Audit log for HubSpot deal → Retell call sync jobs

See supabase/schema.sql for full schema. Existing projects should also run:

• supabase/migrations/20260701_call_sync.sql

• supabase/migrations/20260701_hubspot_enrichment.sql

HubSpot fields stored on retell_sessions after sync:

HubSpot deal → Retell call sync

Syncs deals where ai_call_attempted = true into retell_sessions, linked by hubspot_deal_id.

Matching order (first hit wins):

1. Deal property in HUBSPOT_RETELL_CALL_ID_PROPERTIES (default: retell_call_id, retell_session_id, ai_retell_call_id)

2. Retell call metadata.hubspot_deal_id

3. All syncable Retell calls to the deal's associated contact phone (connected and failed dials: dial_no_answer, dial_busy, telephony_provider_permission_denied)

Failed attempts are stored with end_reason = the Retell disconnection reason and session_outcome = failed_dial.

One-time historical backfill (local or Render shell):

npm run backfill:calls

Ongoing sync — option A: Render Cron Job (recommended)

Ongoing sync — Option B: in-process scheduler (active in render.yaml)

Set on the Render web service:

The server runs an incremental sync ~60s after startup, then every hour. Only deals modified since the last successful sync are re-processed (24h overlap buffer). Overlapping runs are skipped if a previous sync is still in progress.

Redeploy after changing environment variables in Render (Manual Deploy if needed).

Manual full re-sync:

curl -X POST "https://ai-calling-j1hu.onrender.com/cron/sync-call-data?full=true" \
  -H "Authorization: Bearer <MCP_SERVER_SECRET>"

Security

• No secrets in code or .env.example

• .env is gitignored

• Bearer auth on /mcp and /webhooks/retell

• Logs scrub Authorization headers and token values

• All tool inputs validated with Zod