Agent Skill Guide

Everything an AI agent needs to register, fund, and call the Hawaii Conditions MCP Server. Also available as raw markdown for programmatic ingestion.

🌐 MCP Endpoint

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

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

💳 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 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_…) — store immediately, shown only once
  2. Call create_wallet_setup → returns client_secret for saving a card via Stripe
  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 X-MCP-Account

Authenticating requests

X-MCP-Account: mcp_live_<your_api_key>

Also accepted as Authorization: Bearer mcp_live_…

Balance fields (get_balance response)

FieldDescription
balance_centsCurrent spendable balance — decreases with each paid call
balance_usdFormatted, e.g. "$3.80"
original_balance_centsAmount from first top-up — locked forever, never changes
original_balance_usdFormatted, e.g. "$5.00"
low_balancetrue when balance is near zero — agent should self-top-up
threshold_usdThe low-balance threshold value

🧠 Tools

Billing & account management (free)

ToolCostDescription
register_agentFreeCreate account — returns api_key
get_balanceFreeCurrent balance, original load amount, low-balance flag
create_wallet_setupFreeReturns Stripe SetupIntent client_secret for card collection
save_payment_methodFreeAttach a Stripe pm_… payment method
link_stripe_customerFreeLink an existing Stripe cus_… customer ID
recent_transactionsFreeView recent credits and debits on the ledger

Top-up (charged to saved card)

ToolAmountDescription
add_funds_5$5.00Add $5 of prepaid credit
add_funds_10$10.00Add $10 of prepaid credit
add_funds_20$20.00Add $20 of prepaid credit

Data tools (deducted from balance)

ToolCostDescription
pingFreeHealth check — no balance required
get_sun_timesFreeSunrise, sunset, daylight duration by island (HST)
get_weather$0.105-day forecast, UV index, wind, sunrise/sunset
get_surf_conditions$0.10Wave height, period, direction + 3-day forecast
get_trail_status$0.25NPS alerts and state trail closures
get_volcano_status$0.25Live Kīlauea status from USGS HVO
get_ocean_safety$0.50Box jellyfish, rip currents, NOAA marine alerts
get_full_briefing$2.00All five data sources in one call — best value
search_restaurants$0.25Find restaurants by location, cuisine, price, hours
get_restaurant_details$0.15Full hours, reviews, photos by place_id

🏝 Supported islands

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

⚡ Quick-start example

// Step 1 — Register (do this once)
  const reg = await fetch("https://hawaii-conditions.vercel.app/mcp", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0", method: "tools/call",
      params: { name: "register_agent",
                arguments: { agent_id: "my-agent-001", display_name: "My Agent" } },
      id: 1
    })
  });
  const { api_key } = await reg.json(); // store permanently

  // Step 2 — Call a data tool
  const weather = await fetch("https://hawaii-conditions.vercel.app/mcp", {
    method: "POST",
    headers: { "Content-Type": "application/json", "X-MCP-Account": api_key },
    body: JSON.stringify({
      jsonrpc: "2.0", method: "tools/call",
      params: { name: "get_weather", arguments: { island: "maui" } },
      id: 2
    })
  });

🔍 Discovery URLs

URLPurpose
/mcpMCP endpoint
/skill.mdThis skill in raw markdown
/llms.txtLLM system prompt instructions
/agents.txtAgent directives
/.well-known/mcp/server-card.jsonMCP server card
/.well-known/agent-card.jsonAgent card (A2A)
/healthHealth check