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.

Email for booking: Map pre-call get_hubspot_contact output email to the Retell dynamic variable contact_email. Cara must pass email: {{contact_email}} on every book_tour call (also pass hubspotDealId / hubspotContactId when available). Never ask the guest for email. Never use placeholder addresses.

Required on every MCP tool call during a live call:

Never pass JSON null for these fields. Never pass placeholder emails such as need_email@example.com. If booking fails, use the WhatsApp fallback from the tool response and do not tell the guest the tour is booked.

Configure Retell dynamic variables so the pre-call HubSpot tools populate contact_email, deal_id, and contact_id before the call starts.

After a successful booking: If TOUR_BOOKING_EMAIL_ENABLED=true, a React Email notification is sent to TOUR_BOOKING_NOTIFY_EMAIL with the tour time plus links to the HubSpot deal and contact records.

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

# Test tour booking notification email (requires SMTP_PASSWORD)
SMTP_PASSWORD=your_app_password npx tsx scripts/testTourBookingEmail.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 and Notion sync runs

• sync_state — Notion sync cursor (notion_retell_sessions)

• sync_errors — Notion rows that failed and will be retried

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

• supabase/migrations/20260701_call_sync.sql

• supabase/migrations/20260701_hubspot_enrichment.sql

• supabase/migrations/20261023_notion_sync_state.sql

Notion live sync (retell_sessions → Sprints page)

Syncs your existing Supabase retell_sessions table into the Supabase retell_sessions database on your Sprints page.

No new Supabase tables are required.

How live sync works

Upserts are keyed by Session ID (the Retell call_id / Supabase session_id). An existing Notion page is updated. A missing one is created. A second page with the same Session ID is archived.

1. Near real time — after the Retell webhook, call sync, or get_room_pricing writes retell_sessions, that one session is synced in the background. The webhook response does not wait on Notion.

2. Every 5 minutes — Render cron service AI_Calling_notion_sync runs scripts/notion-incremental-sync.ts. It reads rows with updated_at after the cursor in sync_state, 100 at a time. The cursor moves forward only through rows that succeeded, so a bad row is retried next run and does not block later rows from being written.

3. Failures — the Notion error body is stored in sync_errors (session_id + error). Open errors are retried on the next cron run.

Queries and new pages use Notion API 2025-09-03 with data source 3ab762e2-8bfc-8195-986f-000bb2230e5e. Formula columns (Cost (€), Talk minutes, Country, Week (Sat start)) are never written. Cost stays in cents.

The in-process timer was removed. Render's free web service sleeps, so that timer could not keep the sync alive.

Setup (5 steps)

1. Create a Notion internal integration

• Go to notion.so/my-integrations → New integration

• Name: AI Calling Sync

• Copy the Internal Integration Secret → NOTION_API_KEY

2. Share your Sprints page with the integration

• Open your Sprints page

• ⋯ → Connections → AI Calling Sync

• Make sure the Supabase retell_sessions database/section is included

3. Ensure the Notion database exists

On the Sprints page, under Supabase retell_sessions, create (or keep) a table database with these columns:

Session ID (title), Call time, Duration (s), Status, Sentiment, Outcome, Contact, Email, Phone, Deal, Deal stage, Agent, Direction, Cost, Total price, Recording, Retell log, call_transcript, transcript_with_tool_calls, Supabase updated

4. Set Render env vars

Also required by the app process, and copied onto the cron job from the web service: MCP_SERVER_SECRET, HUBSPOT_ACCESS_TOKEN, the HubSpot meeting URLs and slugs. NOTION_CLIENT_ID, NOTION_CLIENT_SECRET, and NOTION_REFRESH_TOKEN are only needed if you keep using OAuth instead of an internal integration secret.

On the Supabase retell_sessions database, open ⋯ → Connections and confirm the integration that owns NOTION_API_KEY is connected. A token that is valid but not shared with that database cannot query or create pages.

OAuth (Option 1): After visiting /auth/notion, the app saves the access and refresh tokens in Supabase sync_state (notion_oauth). That survives Render redeploys even if you do not paste tokens into Render immediately. Keep NOTION_CLIENT_ID and NOTION_CLIENT_SECRET on Render so the app can refresh expired access tokens automatically. Re-authorize once after deploying a build that includes this persistence if sync was connected only in memory before.

Run this once in the Supabase SQL editor before the first deploy of this sync:

supabase/migrations/20261023_notion_sync_state.sql

5. Backfill the gap since 2026-10-01

npm run sync:notion-check
npm run backfill:notion -- --since 2026-10-01T00:00:00Z
npm run sync:notion-check

Dry run (counts only, no Notion writes):

npm run backfill:notion -- --since 2026-10-01T00:00:00Z --dry-run

Health (503 when the cursor is more than 30 minutes behind the newest Supabase row):

curl https://ai-calling-j1hu.onrender.com/health/notion-sync

Connection status:

curl https://ai-calling-j1hu.onrender.com/notion/status

MCP tools catalog on the AI Calling page

Publishes the Retell MCP tool inventory under MCP/General Tools Implemented or Needed on the AI Calling page.

Source of truth: src/mcp/toolCatalog.ts (7 tools from src/mcp/tools.ts).

curl -X POST "https://ai-calling-j1hu.onrender.com/cron/sync-notion-mcp-tools" \
  -H "Authorization: Bearer YOUR_MCP_SERVER_SECRET"

Local:

npm run sync:notion-mcp-tools

Re-runs replace the previous auto-synced block (idempotent).

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