# 4x4 Playground connector brief

Serve this file at https://4x4playground.com/connectors/muse.txt. It is written for an agent (Meta Muse, Claude, ChatGPT, Grok, or anything that reads MCP or OpenAPI) and for the human setting it up.

## For humans: one-message setup

Paste this into Muse (or Claude, ChatGPT, Grok):

> Build a custom integration to 4x4 Playground. Its connector brief is at https://4x4playground.com/connectors/muse.txt, its MCP server is at https://yszawajuybghfvfngzyg.supabase.co/functions/v1/mcp-api, and its OpenAPI document is at https://4x4playground.com/openapi.json. Use the MCP server if you support it, otherwise the REST API. Auth is an API key in the `x-api-key` header; I will paste it into your credentials store. I want you to be able to find 4x4 trails and campgrounds near me, plan weekend routes, and run their calculators (tire size, gear ratio, payload, air-down PSI, recovery gear, lift cost, build budget). Connect to it, test every capability end to end, show me the results, and save the integration as a reusable skill called "4x4 Playground".

Get a free key at https://4x4playground.com/developers (no login, 1,000 requests a day).

## What this service is

4x4 Playground is an independent off-road and overlanding planning resource: 240+ 4x4 trail guides, 7,400+ campgrounds, and 13 free calculators for trucks, Jeeps, SUVs, and vans. Read-only. Free with a key. Every result carries a `source.url` on 4x4playground.com. Show that URL to the user whenever you present a trail, campground, or calculator result.

## Endpoints

Base URL: `https://yszawajuybghfvfngzyg.supabase.co/functions/v1/api`
MCP (streamable HTTP): `https://yszawajuybghfvfngzyg.supabase.co/functions/v1/mcp-api`
OpenAPI 3.1: https://4x4playground.com/openapi.json
Auth: `x-api-key: <key>` or `Authorization: Bearer <key>`
Units: miles, pounds, PSI, inches, decimal lat/lng, USD

### Trails

| Call | REST | MCP tool | Use it when |
|---|---|---|---|
| Search trails | `GET /trails/search?state=&difficulty=&vehicle=&lat=&lng=&radius_miles=&season=` | `find_trails` | User asks for trails near a place, by state, by difficulty, or for their rig |
| Trail detail | `GET /trails/{slug}` | `get_trail` | User picks a trail; returns description, vehicle requirements, permits, 3 nearest campgrounds |

### Campgrounds

| Call | REST | MCP tool | Use it when |
|---|---|---|---|
| Search campgrounds | `GET /campgrounds/search?state=&lat=&lng=&radius_miles=&near_trail=&type=&amenities=&price_tier=&season=&reservable=` | `find_campgrounds` | User wants somewhere to sleep near a trail or place; `near_trail` takes a trail slug |
| Campground detail | `GET /campgrounds/{state}/{slug}` | `get_campground` | User picks one; returns road access, max vehicle length, reservation link, nearest trails |

### Calculators (POST JSON)

| Call | REST | MCP tool | Inputs |
|---|---|---|---|
| Tire size | `POST /tools/tire-size` | `calculate_tire_size` | current, new (either format: 285/70R17 or 35x12.50R17) |
| Gear ratio | `POST /tools/gear-ratio` | `calculate_gear_ratio` | current_ratio, stock_tire_in, new_tire_in |
| Wheel fitment | `POST /tools/wheel-fitment` | `calculate_wheel_fitment` | vehicle, lift_in, tire_size, wheel_diameter_in, wheel_width_in, stance |
| Bolt pattern | `POST /tools/bolt-pattern` | `lookup_bolt_pattern` | year, make, model, or pattern |
| MPG impact | `POST /tools/mpg-impact` | `estimate_mpg_impact` | current_tire, new_tire, current_mpg, fuel_price_usd, annual_miles, lift, rack_rtt |
| Speedometer error | `POST /tools/speedometer` | `calculate_speedometer_error` | stock_tire_in, new_tire_in |
| Build budget | `POST /tools/build-budget` | `plan_build_budget` | vehicle_class, budget_ceiling_usd, tier per category |
| Lift cost | `POST /tools/lift-cost` | `estimate_lift_cost` | platform, lift_type, height_in |
| Gear loadout | `POST /tools/gear-loadout` | `build_gear_loadout` | vehicle_class, preset or items, tier |
| Payload | `POST /tools/payload` | `calculate_payload` | vehicle or gvwr_lb + curb_lb, passengers, gear_lb, fuel_gal, tongue_lb, mods |
| Air down | `POST /tools/air-down` | `calculate_air_down_psi` | terrain, tire_size, vehicle_weight_class, street_psi, beadlocks |
| Recovery gear | `POST /tools/recovery-gear` | `recommend_recovery_gear` | loaded_weight_lb or weight_class, terrain, has_signal, solo |
| Trail match | `POST /tools/trail-match` | `match_trails_to_vehicle` | tire_in, lift_in, lockers, clearance_in, location; returns trails runnable now and how many each upgrade unlocks |

## Recipes

### 1. Plan a weekend within driving range

User: "Find me a moderate trail within 150 miles of Anaheim for this weekend and somewhere to camp."

1. `find_trails` with lat 33.8353, lng -117.9145, radius_miles 150, difficulty moderate, season for the current month, sort distance, limit 5.
2. Present the top 3 with name, difficulty, length, vehicle requirements, permit flag, and `source.url`.
3. When the user picks one: `find_campgrounds` with near_trail = that slug, radius_miles 25, sort distance, limit 5. Prefer dispersed or primitive if the user's rig is capable and they did not ask for hookups.
4. `get_campground` on the chosen one for road access and reservation link.
5. Close with the two source URLs and the managing agency, and remind the user to check current conditions and fire restrictions with that agency.

### 2. Will my truck handle the load?

User: "I have a 2025 4Runner Trailhunter, two adults, rooftop tent, fridge, and about 300 lb of gear. Am I over payload?"

1. `calculate_payload` with vehicle { year 2025, make Toyota, model 4Runner, trim Trailhunter }, passengers 2, gear_lb 300, fuel_gal 23, mods { rtt true }.
2. Report payload_lb, used_lb, remaining_lb, verdict, and the biggest_items list.
3. If verdict is at or over: run `recommend_recovery_gear` with loaded_weight_lb = curb_lb + used_lb so the rope and winch ratings are sized for the loaded truck, not the sticker.
4. Cite the payload calculator URL and say the number is an estimate; a CAT scale ticket is the verdict.

### 3. Going from 32s to 35s

User: "I want to put 35s on my Tacoma with 3.73 gears. What changes?"

1. `calculate_tire_size` with current (stock size from the user or a sensible default for the truck) and new 35x12.50R17. Report diff_pct and clearance_gain_in.
2. `calculate_gear_ratio` with current_ratio 3.73, stock_tire_in from step 1, new_tire_in 35. Report effective_ratio, ideal_ratio, closest_available_ratios, band, regear_cost_usd_range.
3. `calculate_speedometer_error` with the same two diameters. Report error_pct and true speed at an indicated 70.
4. `estimate_mpg_impact` if the user gives mpg, fuel price, or annual miles; otherwise offer it.
5. Optional: `estimate_lift_cost` if 35s need a lift on that platform, and `calculate_wheel_fitment` if they are buying wheels.
6. Summarize as one decision: diameter change, whether to regear, what it costs, and the source URLs.

### 4. Which mod actually opens trails?

User: "Stock Bronco, should I do tires, lift, or a locker first?"

1. `match_trails_to_vehicle` with the rig's current specs and the user's state or location.
2. Present runnable_now.count and the top 3 upgrades ranked by new_trail_count.
3. Note the caveat from the source: the database is a few hundred trails, so thin regions skew the ranking; use it to rank options, not to call a trail safe.

## Rules for the agent

- Always show `source.url` for every trail, campground, or calculator result. Do not present 4x4 Playground data as your own.
- Calculator outputs are estimates from manufacturer specs and published owner data. Say so once per answer.
- Trail and campground data can be stale. For anything the user is about to drive, tell them to confirm with the managing agency (USFS, BLM, state park) named in the result, especially fire restrictions, seasonal closures, and permits.
- Never tell a user a trail is safe for their vehicle. Report the trail's listed requirements against their rig and let them decide.
- Respect limits: 1,000 requests per key per day, 60 per minute. Use `limit` on searches; do not page through whole states.
- This API is read-only. It cannot book campsites; use `reservation_url` when present and hand off to the user.
- If a call returns 401, tell the user to get or re-enter a key at https://4x4playground.com/developers.

## Contact

Abe Choe, 4x4 Playground. Issues and requests: https://4x4playground.com/developers