Dewy Resort Hotel - Sample Application

Enterprise MCP Design Patterns for LLM Productivity

A demonstration of how to design Model Context Protocol (MCP) servers that maximize AI agent productivity while maintaining backend system integrity, performance, security, and scale.

---

What This Demonstrates

This sample application showcases enterprise-grade MCP architecture patterns that solve real-world challenges when integrating LLMs with backend systems:

The Problem

Most MCP implementations give AI agents direct database access or expose raw APIs, leading to:

• ❌ Poor performance - Agents make 10+ API calls for simple tasks
• ❌ Data integrity issues - Agents create invalid state transitions
• ❌ Security vulnerabilities - Overly permissive tool access
• ❌ Scalability bottlenecks - No caching, retries, or rate limiting
• ❌ Poor user experience - Slow responses, frequent failures

The Solution: Compositional MCP Architecture

This project demonstrates a two-tier tool design that balances LLM flexibility with enterprise requirements:

🎯 Orchestrators (High-level tools) - Optimized for common scenarios

• Encode business rules and prerequisites
• Execute multi-step workflows in < 3 seconds
• Handle state transitions in correct dependency order
• Provide great UX for 80% of use cases

🧩 Atomic Skills (Building blocks) - For edge cases and flexibility

• Single-responsibility operations
• Composable by AI agents at runtime
• Enable handling of unexpected scenarios
• Maintain proper authorization boundaries

Key Result: AI agents get fast, validated workflows for common tasks AND the flexibility to handle edge cases intelligently.

---

Why This Matters

Enterprise MCP Architecture - Persona-based servers with orchestrators and atomic skills

Real-World Example: Guest Check-In

Check-in orchestrator: < 3 seconds, 6 API calls, validates prerequisites, ensures correct state transitions

Traditional Approach (LLM with raw Salesforce access):

Agent makes 15+ separate API calls:
1. Search for guest → 400ms
2. Validate guest exists → 200ms
3. Search for booking → 400ms
4. Check booking status → 200ms
5. Validate room number → 200ms
6. Search for room → 400ms
7. Check room status → 200ms
8. Update booking status → 300ms
9. Update room status → 300ms
10. Update opportunity → 300ms
... error handling, retries ...

Total time: 8-12 seconds
Failure rate: 15-20% (race conditions, validation errors)

Enterprise MCP Approach (Orchestrator):

Agent calls one orchestrator:
POST /check-in-guest {guest_email, check_in_date}

Orchestrator internally:
- Validates prerequisites in parallel (3 reads)
- Executes state transitions in order (3 updates)
- Handles errors gracefully
- Ensures data integrity

Total time: < 3 seconds
Failure rate: < 2% (only fails on legitimate business rule violations)

Result: 3-4x faster, 90% fewer errors, better user experience.

Edge Case Handling with Atomic Skills

Scenario: Guest says "I need towels in room 101" but contact doesn't exist in system

Orchestrator-only approach:

• ❌ Fails with "Contact not found" error
• ❌ Agent can't proceed
• ❌ Poor user experience

Compositional approach (Orchestrator + Atomic Skills):

• ✅ Agent detects missing contact
• ✅ Agent composes: create_contact → upsert_case
• ✅ Handles edge case with proper approval authority
• ✅ Great user experience

Key Insight: Give agents both optimized workflows AND building blocks for flexibility.

---

Architecture Principles

1. Zero Direct System Integrations

All data movement flows through Workato integration hub

❌ DON'T: Hotel App → Salesforce (tight coupling)
❌ DON'T: Hotel App → Stripe (security risk)
❌ DON'T: LLM → Salesforce (no validation)

✅ DO: Hotel App → Workato → Salesforce (orchestrated)
✅ DO: LLM Agent → MCP Server → Workato → Backends (validated, secure)

Benefits:

• Performance: Workato handles caching, connection pooling, retries
• Security: Single integration layer with centralized auth
• Maintainability: Backend changes don't break frontend
• Observability: All integration traffic in one place

2. Persona-Based MCP Servers

Organize tools by user role and "jobs to be done"

Guest MCP Server:
├── Orchestrators: check_in_guest, checkout_guest, service_request
└── Atomic Skills: search_contact, search_booking, upsert_case

Staff MCP Server:
├── Orchestrators: maintenance_request, assign_room, update_case_status
└── Atomic Skills: create_contact, search_room, update_room_status

Benefits:

• Security: Users only access tools appropriate for their role
• Performance: Smaller tool context = better LLM reasoning
• Usability: Relevant tools for each persona
• Scale: Independent servers can be optimized separately

3. Idempotency and State Validation

Every orchestrator validates prerequisites and checks for duplicate operations

Example: Check-in orchestrator validates:

• ✅ Guest exists (Contact.id)
• ✅ Reservation exists (Booking.status = Reserved)
• ✅ Room is available (Hotel_Room.status = Vacant)
• ✅ No existing check-in for this booking (idempotency)

Benefits:

• Data integrity: No invalid state transitions
• Reliability: Retry-safe operations
• Error handling: Clear, actionable error messages
• Audit trail: All validation logged

4. Performance Optimization

Orchestrators minimize API calls and latency

Techniques demonstrated:

• Parallel execution: Read operations execute concurrently
• Dependency ordering: Updates execute in correct sequence
• Batch operations: Multiple updates in single transaction where possible
• Caching: Workato caches connection pools and reference data
• Circuit breakers: Fail fast on downstream outages

Result: Typical orchestrators complete in < 3 seconds with 4-6 API calls.

---

What's Included

MCP Server Implementation (Workato)

33 Recipes organized as MCP tools:

12 Orchestrators (High-level workflows):

• check_in_guest - Multi-object state transition (< 3s, 6 API calls)
• checkout_guest - Payment processing + room release
• service_request - Guest service case creation
• maintenance_request - Staff maintenance workflow
• create_booking_orchestrator - Full booking with availability check
• Additional orchestrators for case management, search workflows

21 Atomic Skills (Building blocks):

• Salesforce (15): search_contact, search_booking, search_room, create_contact, update_booking_status, upsert_case, etc.
• Stripe (6): create_customer, create_payment_intent, confirm_payment, retrieve_status, create_refund

Hotel Management Application (Next.js)

• Guest Portal: Service requests, room controls, billing, AI assistant
• Manager Portal: Dashboard, maintenance management, room operations
• MCP Integration: Demonstrates how to call enterprise MCP servers from application code
• Local Database: SQLite for app-specific data (sessions, UI state)

Backend Systems

• Salesforce: System of record (Bookings, Rooms, Cases, Contacts, Opportunities)
• Stripe: Payment processing (optional)
• Twilio: SMS notifications (optional)

---

Quick Start

One-Line Install (Recommended)

Mac/Linux:

curl -fsSL https://raw.githubusercontent.com/workato-devs/dewy-resort/main/bootstrap.sh | bash

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -Command "Invoke-Expression (curl https://raw.githubusercontent.com/workato-devs/dewy-resort/main/bootstrap.ps1 -UseBasicParsing)"

The bootstrap script automatically installs all dependencies (Node.js v20, Git) and sets up the project.

Then change into the project directory:

cd dewy-resort

Manual Setup

Prerequisites:

• Node.js 20+
• Workato Developer sandbox (free Developer sandbox)
• Salesforce Developer org (free Developer Edition)
• Stripe Developer account (Stripe Developer sign up)
• Workato CLI (wk) — macOS/Linux: brew install workato-devs/tap/wk / Windows: scoop bucket add workato-devs https://github.com/workato-devs/scoop-bucket && scoop install wk

1. Initialize Project

# Copy env template
cp .env.example app/.env

# Install app dependencies and initialize local database
cd app
npm install
npm run db:setup
cd ..

2. Deploy Salesforce Metadata ⭐

Salesforce is the system of record — deploy it first.

# Verify CLIs are installed
make setup

# Authenticate to Salesforce (opens browser)
sf org login web --alias myDevOrg

# Deploy metadata and seed data
make sf-deploy org=myDevOrg

📚 See: Salesforce Setup

3. Deploy Workato MCP Server ⭐

Workato implements the enterprise MCP architecture.

# Authenticate with your Workato workspace
make workato-login

# Initialize Workato project and push recipes
make workato-init
make push

Next, configure connections in the Workato UI:

1. Go to Projects → Workspace Connections and connect your Salesforce org
2. Optionally connect Stripe (Sandbox mode, sk_test_ key)

# Start all recipes
make start-recipes

⚠️ IMPORTANT: 4 recipes with dynamic SOQL queries may need their Salesforce connection linked manually before they'll start. See the detailed guide for steps.

📚 See: Workato Setup

4. Configure API & MCP

Set up API collections, endpoints, and MCP servers:

# Create API collections, endpoints, and API client (writes credentials to app/.env)
make setup-api

# Enable all API endpoints
make enable-api-endpoints

# Create MCP servers and write URLs/tokens to app/.env
make setup-mcp

5. Start Application

app/scripts/dev-tools/server.sh start

Open http://localhost:3000

---

Learning Path

For Workshop Participants

Goal: Understand enterprise MCP design patterns

1. Start here: Review architecture diagrams in app/docs/architecture/
2. Explore: Compare orchestrator vs atomic skill patterns
3. Observe: Check-in orchestrator flow (prerequisites, state transitions, error handling)
4. Experiment: Try edge cases (missing contact, double check-in, invalid room)
5. Reflect: Why are orchestrators faster? Why do atomic skills matter?

For Developers Building MCP Servers

Goal: Apply these patterns to your own projects

1. Architecture: Study system-architecture.png
2. Implementation: Review Workato recipes in workato/ directory
3. Patterns: Read WORKATO_SETUP.md for detailed pattern explanations
4. Adaptation: Consider how to apply orchestrator + atomic skill pattern to your domain

Key Takeaways

✅ Orchestrators for common scenarios - Fast, validated, great UX

✅ Atomic skills for flexibility - Handle edge cases intelligently

✅ Zero direct integrations - All through central hub

✅ Persona-based servers - Security, performance, usability

✅ Idempotency and validation - Data integrity, reliability

✅ Performance optimization - Parallel reads, dependency ordering

---

Additional Resources

Setup Guides

• Salesforce Setup - Deploy custom objects and seed data
• Workato Setup - Deploy MCP server recipes
• Architecture Diagrams - Visual documentation of all workflows

Optional Features

• Stripe Integration - Payment processing
• Cognito Authentication - User auth (workshop convenience)
• Bedrock AI Chat - AI assistants (optional)

Technical Details

• Salesforce Metadata - Complete object and field documentation
• Project Structure - Codebase organization
• CLI Commands - Automation scripts

---

Project Structure

dewy-resort/
├── workato/                      # ⭐ MCP SERVER IMPLEMENTATION
│   ├── recipes/
│   │   ├── atomic-salesforce-recipes/  # 15 atomic skills
│   │   ├── atomic-stripe-recipes/      # 6 payment atomic skills
│   │   ├── orchestrator-recipes/       # 13 high-level orchestrators
│   │   ├── home-assistant/             # Home Assistant integration
│   │   ├── sf-api-collection/          # API Collection definitions
│   │   └── Workspace Connections/      # Connection configs
├── app/                          # Next.js application
│   ├── src/                      # Application source
│   ├── docs/
│   │   └── architecture/         # ⭐ ARCHITECTURE DIAGRAMS
│   │       ├── system-architecture.png
│   │       ├── guest-checkin-flow.png
│   │       ├── guest-checkout-flow.png
│   │       ├── guest-service-request-flow.png
│   │       └── maintenance-request-flow.png
│   └── public/                   # Static assets
├── vendor/
│   ├── workato/                  # Workato docs & scripts
│   │   ├── docs/
│   │   │   └── WORKATO_SETUP.md
│   │   └── scripts/
│   ├── salesforce/               # Salesforce metadata & deployment
│   │   ├── force-app/            # Custom objects, fields, app
│   │   ├── data/                 # Seed data
│   │   ├── docs/
│   │   │   └── SALESFORCE_SETUP.md
│   │   └── scripts/
│   │       └── deploy.sh
│   ├── aws/                      # CloudFormation templates
│   └── okta/                     # Okta auth config

---

CLI Commands

# Setup
make setup                        # Verify CLI installations
make workato-login                # Authenticate wk CLI with API token

# Workato (MCP Server) — requires wk CLI (brew install workato-devs/tap/wk)
make workato-init                 # Initialize wk project & pull recipes
make validate                     # Lint all recipes
make push                         # Push recipes to workspace
make pull                         # Pull recipes from workspace
make start-recipes                # Start all recipes
make stop-recipes                 # Stop all recipes
make setup-api                    # Create API collections, endpoints & client
make enable-api-endpoints         # Enable API endpoints
make setup-mcp                    # Create MCP servers & write config to app/.env

# Salesforce (Backend)
make sf-deploy org=<alias>        # Deploy metadata and seed data

# Diagnostics
make status                       # Check all CLI status
make doctor                       # Verify CLI installations

---

Mock Mode (Development Only)

For frontend development without backend setup:

# In .env
WORKATO_MOCK_MODE=true

# Restart server
npm run dev

⚠️ Note: Mock mode simulates MCP responses. Use for frontend work only, not for learning MCP architecture patterns.

---

Optional Features

Cognito Authentication (Workshop Convenience)

For workshops where participants don't have their own auth:

AUTH_PROVIDER=cognito
# Deploy Cognito User Pool
cd aws/cloudformation
./deploy.sh dev http://localhost:3000/api/auth/cognito/callback http://localhost:3000 dewy-hotel

Bedrock AI Chat (Optional)

AI-powered chat assistants (demonstrates LLM + MCP integration):

# Deploy Identity Pool
cd aws/cloudformation
./deploy-identity-pool.sh dev <user-pool-id> <client-id>

# Configure in .env
COGNITO_IDENTITY_POOL_ID=your_pool_id

---

Technology Stack

• MCP Server: Workato (33 recipes organized as orchestrators and atomic skills)
• Backend Systems: Salesforce (CRM), Stripe (payments), Twilio (SMS)
• Application: Next.js 14, React, TypeScript, Tailwind CSS
• Database: SQLite (local app data only)
• Auth: Amazon Cognito (optional) or mock mode
• AI: Amazon Bedrock (optional chat assistants)

---

Why Workato?

This sample uses Workato as the MCP server implementation, but the architectural patterns apply to any integration platform:

✅ Visual recipe builder - Easy to understand workflows

✅ Built-in connectors - Salesforce, Stripe, Twilio out of the box

✅ API Collections - Native REST API exposure

✅ Enterprise features - Error handling, retries, logging, monitoring

✅ Workshop-friendly - Visual representation aids learning

The patterns work with: Custom APIs, serverless functions, other orchestration systems, etc.

---

License

MIT

---

Questions?

This is a sample application for teaching enterprise MCP design patterns. The goal is to demonstrate how to build MCP servers that maximize LLM productivity while maintaining backend integrity, performance, security, and scale.

Focus areas:

• Why orchestrators matter for performance and UX
• When to use atomic skills vs orchestrators
• How to design persona-based MCP servers
• Patterns for idempotency and state validation
• Zero direct system integrations architecture

For implementation details, see the setup guides in vendor/workato/docs/ and vendor/salesforce/docs/.