Front Desk

Try it: live app · demo call (Chrome or Edge) · MCP endpoint https://18-190-98-99.sslip.io/b/main-street-barbers/mcp · code (MIT)

Inspiration

Small service businesses run on appointments, but the person who should answer the phone is usually busy with a customer. A barber with scissors in hand can't pick up, so the caller books somewhere else. We wanted a receptionist that never misses a call, speaks naturally, and keeps the owner's schedule up to date, while the owner stays in control of everything.

What it does

Front Desk is a voice receptionist for any business that runs on appointments: barbershops, salons, spas, clinics, physical therapy, pet groomers, tattoo studios, personal trainers, tutors. Customers talk to it like they would to a person:

• Book: "Anything for a haircut this morning?" → it checks real availability, offers times and books the one the customer picks. Every booking needs a name and a phone number, asked for together, and caller ID fills in the number.
• Recognize regulars: "Hey, it's Sam." → "Welcome back, Sam! Last time was a beard trim with Diego. Want the usual?"
• Waitlist that fills itself: if a time is full, the customer can join the waitlist. When someone cancels, the slot is booked for the next person automatically, so the chair never sits empty.
• Cancel and reschedule by phone, keeping the same staff member when possible, and "first available" for the earliest slot.
• Owner by voice: "Block Diego's afternoon, he has a dentist appointment" takes the time off and flags who was already booked; "How's my day looking?" gives customers, expected revenue, waitlist fills and blocked time.

And the owner can do everything by hand in the Front Desk app: sign up, pick a type of business (it starts with fitting services, hours and words, like "stylists" and "clients" for a salon), then manage a day calendar by team member (book, move, complete, no-show, cancel, notes, block time), customers with full visit history, the waitlist, services, team, opening hours and settings. A live board for a screen at the front desk flashes each booking, cancellation and waitlist fill as it happens. One account can run several businesses, each with its own data and its own MCP endpoint.

How we built it

• MCP server (Python, MCP SDK 2.2.0): nine tools over Streamable HTTP, protocol 2025-11-25, with one endpoint per business (/b/<business>/mcp): list_services, check_availability, book_appointment, cancel_appointment, reschedule_appointment, join_waitlist, customer_history, block_time, daily_summary. Every tool has a title, read-only/destructive annotations and structured output (outputSchema + structuredContent), plus a short speech sentence ready for voice. Customer tools are open like a phone line; owner tools need the business's API key. Round trips stay well under the 500 ms Alexa+ asks for (tested).
• Agent on Amazon Bedrock: Amazon Nova Pro through the Converse API with tool use. On every utterance the agent reads the business's MCP tools (tools/list), converts them to toolSpec, lets Nova choose, and executes the calls on the MCP server (tools/call), the same way Alexa+ would. Guardrails in the agent keep voice flows predictable (ask "Want the usual?" and wait, only join the waitlist with the customer's OK, never tell one caller about another), and if a Nova model has no quota or fails, it retries and falls back to the next one.
• Multi-tenant platform: accounts with scrypt passwords and HttpOnly session cookies, a platform database for businesses and API key hashes, and one SQLite database per business. The business being served is a per-request context, so the same tools serve every business without mixing data. 11 business types with their own services, hours and vocabulary.
• Simulated Alexa+ experience: Alexa+ developer tools are in preview, so each business has a browser phone line with speech recognition and speech output (Web Speech API, en-US), hands-free turn-taking, push-to-talk, follow-up listening and caller ID. A "Behind the voice" panel shows every MCP call with its arguments and latency.
• AWS deployment: one CloudFormation template creates an EC2 instance (Amazon Linux 2023) behind Caddy with HTTPS, an Elastic IP, and an IAM role that can only invoke Amazon Nova, so there are no access keys anywhere. Administration goes through Systems Manager (no SSH), and updates are pushed with SSM Run Command.
• Quality: 144 automated tests (booking rules, the full MCP round trip, the agent loop with a scripted model, the platform and owner API), validation with the MCP Inspector, and a script that runs the whole demo against the real Nova model before recording. The demo video itself is recorded and edited from code against the deployed app (scripts/video).

Challenges we ran into

• Nova quota on a new account: our first Bedrock call returned "Too many tokens per day". Every Nova daily quota on the new Free-plan account was 0 and marked non-adjustable, so we opened an AWS Support case; it took about two days. Meanwhile we built a rehearsal mode that drives the same MCP tools without the model, so the rest of the product kept moving.
• Model behavior in voice flows: Nova Lite spoke its <thinking> reasoning and sometimes failed with "invalid sequence as part of ToolUse"; smaller models drifted from the script. We moved to Nova Pro first, added retries and guardrails, and test the full demo against the real model.
• SDK changes: MCP SDK 2.x renamed FastMCP, moved transport options, only fills structuredContent for dict[str, Any], and answers 421 behind a proxy unless the public host is allowed.
• Credentials: aws login credentials only work in boto3 with botocore[crt], which nothing in the flow mentions.
• Voice in the browser: making speech recognition reliable took real work: not cutting people off at the first pause, restarting when the browser drops the recognizer, and never listening to its own voice.

All of these are documented in our friction log.

Accomplishments that we're proud of

• A real MCP round trip in every turn of the conversation, visible on screen with millisecond timings.
• A waitlist that turns cancellations into bookings automatically.
• A complete product, not just a voice demo: any business type, owner accounts, and an app where the owner can do everything by hand.
• A deployment with no access keys: an IAM role scoped to Nova, HTTPS, and no SSH.

What we learned

MCP tools designed for voice need short, ready-to-speak answers and clear read/write annotations; the model then mostly orchestrates. Small guardrails around the model (who to ask, when to wait) matter more for voice than a longer prompt. And building the fallback path early saved the project when a dependency was blocked.

What's next for Front Desk

• Publish it as a real Alexa+ add-on with OAuth 2.1 (PKCE) once the developer tools open up.
• SMS confirmations and reminders, and notifying the waitlisted customer when they get a slot.
• Calendar sync (Google, Outlook) and deposits for no-show-prone services.

Built With

• alexa
• amazon-bedrock
• amazon-ec2
• amazon-nova
• aws-cloudformation
• aws-iam
• aws-systems-manager
• caddy
• model-context-protocol
• python
• sqlite
• starlette
• uvicorn
• web-speech-api