Nightlife Search MCP Server

nightlife-mcp

MCP server for nightlife event discovery backed by Supabase.

Quick Start

Production endpoint: https://api.nightlife.dev/mcp

1. Get a free API key at nightlife.dev
2. Add to Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "nightlife": {
      "url": "https://api.nightlife.dev/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

For curl, TypeScript SDK, and other clients, see `CLIENT_SETUP.md`.

Implemented (v0.3)

• search_events
• get_tonight
• get_event_details
• search_venues
• get_venue_info
• search_performers
• get_performer_info
• log_unmet_request
• create_vip_booking_request
• get_vip_booking_status
• get_vip_table_availability
• get_vip_table_chart
• get_recommendations (v0.2, behind MCP_ENABLE_RECOMMENDATIONS=true)
• Streamable HTTP endpoint with API-key middleware
• Structured tool output schemas (outputSchema)
• Deterministic tool error payloads with stable error codes
• Runtime request/tool metrics exposed at /health

Prerequisites

• Node.js 18+
• Supabase project URL + service role key

Setup

cp .env.example .env
npm install

Set env vars in .env:

• SUPABASE_URL
• SUPABASE_SERVICE_ROLE_KEY

Optional:

• DEFAULT_CITY (default: tokyo)
• MCP_TOP_LEVEL_CITIES (default example: tokyo,san-francisco; controls available_cities in unsupported-city responses)
• DEFAULT_COUNTRY_CODE (default: JP)
• NIGHTLIFE_BASE_URL (default: https://nightlifetokyo.com)
• MCP_HTTP_REQUIRE_API_KEY (default: true)
• MCP_HTTP_USE_DB_KEYS (default: true)
• MCP_HTTP_ALLOW_ENV_KEY_FALLBACK (default: true)
• MCP_HTTP_API_KEYS (comma-separated legacy fallback keys)
• MCP_ENABLE_RECOMMENDATIONS (default: false; enables get_recommendations)

DB API Key Mode (Recommended)

HTTP authentication can use persistent API keys from Supabase plus quota tracking.

1. Run SQL migration in your Supabase SQL editor:

-- copy file contents from:
-- supabase/migrations/20260219094000_mcp_api_keys.sql

2. Ensure DB auth flags are enabled in .env:

MCP_HTTP_REQUIRE_API_KEY=true
MCP_HTTP_USE_DB_KEYS=true
MCP_HTTP_ALLOW_ENV_KEY_FALLBACK=true

3. Create an API key record:

npm run key:create -- --name claude-desktop --tier starter --daily-quota 1000 --minute-quota 60

This prints the raw api_key once. Save it securely and use it in MCP HTTP calls.

If the DB RPC is unavailable, fallback to MCP_HTTP_API_KEYS works only when MCP_HTTP_ALLOW_ENV_KEY_FALLBACK=true.

Concierge Unmet Request Backlog

Public concierge flows can log unsupported user intents to Supabase.

Run migration:

-- copy file contents from:
-- supabase/migrations/20260226_concierge_unmet_requests.sql

Then call MCP tool log_unmet_request when no good answer exists from available nightlife data.

VIP Booking Phase 1

VIP table booking submission and status tracking are backed by Supabase.

Run migration:

-- copy file contents from:
-- supabase/migrations/20260227143000_vip_phase1_requests_and_queue.sql
-- supabase/migrations/20260228124500_add_vip_booking_enabled_to_venues.sql
-- and if already deployed before 2026-02-28:
-- supabase/migrations/20260228111000_vip_outward_language_defaults.sql
-- supabase/migrations/20260301010000_vip_table_availability_chart.sql
-- supabase/migrations/20260301114000_vip_table_chart_storage_bucket.sql
-- supabase/migrations/20260303093000_vip_dashboard_admin_edits.sql

Then call MCP tools:

• create_vip_booking_request
• get_vip_booking_status
• get_vip_table_availability (read per-day table availability by venue/date range)
• get_vip_table_chart (read structured table chart with optional per-date status overlay and optional layout_image_url)

Conversation policy for create_vip_booking_request:

• Confirm booking date/time in venue local time before submitting.
• Use dual-date confirmation wording, especially for late-night arrivals (00:00-05:59).
• Required confirmation template:
  • Just to confirm: you want a table for [Night Day] night ([Night Date]), arriving around [Time] on [Arrival Day], [Arrival Date] ([Timezone]). I'll submit that as [Night Day] night with [Time] arrival. Is that correct?
• If the user gives a time like 2am without a day, ask:
  • Do you mean 2:00 AM after Thursday night (Friday morning), or after Friday night (Saturday morning)?
• If the user changes day, regenerate confirmation before submission.

Ops-tier sessions also have internal queue tools:

• list_vip_reservations (all outstanding reservations; default statuses: submitted, in_review, confirmed)
• list_vip_requests_for_alerting (due alerts only)
• `mark_vip