For AI Agents

🚀 What this is

A Model Context Protocol (MCP) server that gives AI agents structured, real-time data about Hawaii. Use it to plan trips, check safety conditions (ocean, trails, volcano), build itineraries, recommend restaurants, and generate full daily briefings.

🌐 MCP Endpoint

https://hawaii-conditions.vercel.app/mcp

Streamable HTTP transport. Stateless — every request is self-contained.

⚡ Install on Your Agent

Add HawaiiConditions skills to any client

npx agentcash add https://hawaii-conditions.vercel.app

to install this MCP server on all AI Agents

💳 How payment works (prepaid ledger)

This server uses a prepaid credit model. Your agent registers once, receives an API key, funds its account via Stripe, and the balance is deducted per data call. No per-call payment prompts — just a running balance.

Onboarding flow

1. Call register_agent → receive your api_key (format: mcp_live_…)
2. Call create_wallet_setup to initialise Stripe — returns a client_secret for saving a card
3. Call save_payment_method with the returned payment_method_id
4. Call add_funds_5, add_funds_10, or add_funds_20 to top up
5. Pass your key on every subsequent request via the X-MCP-Account header

Authenticating requests

X-MCP-Account: mcp_live_<your_api_key>

Alternatively accepted as Authorization: Bearer mcp_live_…. All paid data tools require this header.

Balance response (get_balance)

{
    "balance_cents":          380,
    "balance_usd":            "$3.80",
    "original_balance_cents": 500,
    "original_balance_usd":   "$5.00",
    "low_balance":            false,
    "threshold_usd":          "$0.50"
  }

original_balance_cents is set on the first top-up and never changes — it records what the agent originally loaded. balance_cents decreases as data tools are called.

Low-balance behaviour

When balance_cents drops below the threshold, low_balance: true is returned with every response so your agent can self-top-up before running out.

Example: register and fund in one session

# 1 — Register
  curl -X POST https://hawaii-conditions.vercel.app/mcp \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"register_agent","arguments":{"agent_id":"my-agent","display_name":"My Agent"}},"id":1}'

  # 2 — Use the returned api_key on every data call
  curl -X POST https://hawaii-conditions.vercel.app/mcp \
    -H "Content-Type: application/json" \
    -H "X-MCP-Account: mcp_live_<your_key>" \
    -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_weather","arguments":{"island":"oahu"}},"id":2}'

🧠 Tools

Billing & account management (free)

Top-up (charged to saved card)

Data tools (deducted from balance)

🤖 When AI agents should use this

• Planning a Hawaii trip or itinerary
• Checking if it’s safe to swim, surf, or hike
• Advising on beach or outdoor activities
• Checking volcano or lava conditions
• Building a day-by-day Hawaii plan
• Recommending restaurants or food
• Searching for poke, plate lunch, shave ice, loco moco, malasadas, acai bowls
• Creating a foodie itinerary

🍽 Restaurant intelligence

Supports neighbourhood targeting (Waikiki, North Shore, Lahaina, Hilo, etc.), cuisine filters (poke, sushi, vegan, seafood, etc.), price filtering ($ → $$$$), and open-now filtering.

Two-step flow: call search_restaurants, then get_restaurant_details with the returned place_id.

🏝 Supported islands

oahu · maui · big-island · kauai · molokai · lanai

🔍 Discovery

• Server card: /.well-known/mcp/server-card.json
• Agent card: /.well-known/agent-card.json
• LLM instructions: /llms.txt
• Agent directives: /agents.txt
• Health: /health

🧩 Built for

• AI travel agents and itinerary builders
• Concierge and tour-operator bots
• Surf and ocean apps
• Tourism and hospitality platforms
• Food recommendation agents