Developer reference

Byway MCP

The full tool surface Byway ships over the Model Context Protocol — endpoint, authentication, every tool's schema, and worked examples. Reads live from https://www.byway.world/api/mcp.

v1.7.010 tools2 require sign-in

Quick start

Endpoint

https://www.byway.world/api/mcp

Streamable HTTP, stateless — POST only, a plain GET answers 405 by design.

Add it to a client

Claude Desktop, Cursor and most MCP hosts accept a remote server block like this:

{
  "mcpServers": {
    "byway": {
      "url": "https://www.byway.world/api/mcp"
    }
  }
}

List the tools with curl

curl -s -X POST https://www.byway.world/api/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Authentication

Public tools

No sign-in. Anonymous calls are metered per IP address; over the limit a tool returns a clean rate_limited error rather than a stack trace.

OAuth-gated tools

Reach a paid provider (routing, planning) and are metered per user, not per IP. A call without a Bearer token receives a 401 with a WWW-Authenticate header that most hosts use to trigger sign-in automatically.

/.well-known/oauth-protected-resource/api/mcp
/.well-known/oauth-authorization-server

Tools

search_byways

Search scenic byways

PublicRead-only

Param	Type	Required	Description
query	string	No	Name text to match
state	string	No	Two-letter US state code
country	string	No	ISO-2 country (US or a regional territory); a non-US value searches regional routes instead of the federal roster
limit	integer (1–25)	No	Rows to return

curl -s -X POST https://www.byway.world/api/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_byways","arguments":{"state":"UT","limit":3}}}'

Example result: Found 3 byways: - Bonneville Salt Flats Byway (UT) — https://www.byway.world/byways/bonneville-salt-flats-byway - ...

get_byway

Get byway details

PublicRead-only

Param	Type	Required	Description
slug	string	Yes	Byway slug from search_byways

curl -s -X POST https://www.byway.world/api/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_byway","arguments":{"slug":"bonneville-salt-flats-byway"}}}'

Example result: Bonneville Salt Flats Byway — UT, 26 mi. 4 scenic lookouts on route. https://www.byway.world/byways/bonneville-salt-flats-byway

search_lookouts

Search scenic lookouts

PublicRead-only

Param	Type	Required	Description
byway	string	No	Byway slug — provide this or state
state	string	No	Two-letter US state code — provide this or byway
limit	integer (1–50)	No	Rows to return

curl -s -X POST https://www.byway.world/api/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_lookouts","arguments":{"byway":"bonneville-salt-flats-byway"}}}'

Example result: Found 4 lookouts: - Salt Flats Overlook on Bonneville Salt Flats Byway — https://www.byway.world/lookouts/salt-flats-overlook

get_itinerary

Get road-trip itinerary

PublicRead-only

Param	Type	Required	Description
slug	string	Yes	Itinerary slug

curl -s -X POST https://www.byway.world/api/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_itinerary","arguments":{"slug":"pacific-coast-highway"}}}'

Example result: Pacific Coast Highway — CA. 12 waypoints. https://www.byway.world/itineraries/pacific-coast-highway

plan_drive

Plan a byway

OAuthWrite

Param	Type	Required	Description
origin	string	Yes	Starting point (city or place name)
destination	string	Yes	Where the drive ends (city or place name)
budget_min	integer (30–960, default 240)	No	Total minutes for the whole trip, driving plus stops — set well above the direct drive time to leave room for stops
depart_at	string (ISO 8601 with offset, ≤14 days out)	No	Departure time — defaults to now; hours and weather verdicts are real only inside the forecast horizon
interests	string[]	No	Taste categories to weight stops
pace	string (leisurely \| balanced \| efficient)	No	Trip pace
save	boolean	No	Save the trip to the connected Byway account

curl -s -X POST https://www.byway.world/api/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H 'authorization: Bearer <your-oauth-token>' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plan_drive","arguments":{"origin":"Bozeman, MT","destination":"West Yellowstone, MT","budget_min":300,"pace":"balanced"}}}'

Example result: A real routed plan: verified stops, honest timing, official scenic byways. Requires a connected Byway account (OAuth sign-in) — see Authentication below.

search_places

Search atlas places

PublicRead-only

Param	Type	Required	Description
kind	enum (place kind)	No	Place type to filter on — see /places for the full kind list
state	string (length 2)	No	Two-letter US state code; requires kind
name	string	No	Place name text
lat	number (-90…90)	No	Latitude to search near
lon	number (-180…180)	No	Longitude to search near
radiusMi	number	No	Miles around lat/lon
limit	integer	No	Rows to return

curl -s -X POST https://www.byway.world/api/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_places","arguments":{"kind":"waterfalls","state":"OR","limit":3}}}'

Example result: Found 3 places: - Multnomah Falls (OR) — a 620-foot waterfall on the Historic Columbia River Highway — https://www.byway.world/places/waterfalls/multnomah-falls-3f9a2c1d

get_place

Get place details

PublicRead-only

Param	Type	Required	Description
url	string	No	The place's byway.world /places URL — provide this, or kind + slug
kind	enum (place kind)	No	Place type
slug	string	No	Place slug, ending in the row's 8-hex id

curl -s -X POST https://www.byway.world/api/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_place","arguments":{"url":"https://www.byway.world/places/waterfalls/multnomah-falls-3f9a2c1d"}}}'

Example result: Multnomah Falls (OR) — a 620-foot waterfall on the Historic Columbia River Highway. https://www.byway.world/places/waterfalls/multnomah-falls-3f9a2c1d Records: https://en.wikipedia.org/wiki/Multnomah_Falls · https://www.wikidata.org/wiki/Q6934977

places_on_byway

Places on a byway

PublicRead-only

Param	Type	Required	Description
byway	string	Yes	Byway slug from search_byways
kind	enum (place kind)	No	Place type to filter on
bandMi	number	No	Miles either side of the route
limit	integer	No	Rows to return

curl -s -X POST https://www.byway.world/api/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"places_on_byway","arguments":{"byway":"historic-columbia-river-highway","kind":"waterfalls"}}}'

Example result: 6 atlas places along Historic Columbia River Highway (5 on the road itself). - Multnomah Falls (OR) — 0.1 mi — https://www.byway.world/places/waterfalls/multnomah-falls-3f9a2c1d

search_destinations

Search destinations

PublicRead-only

Param	Type	Required	Description
q	string (min length 2)	No	City name text to match — provide this or state
state	string (two letters)	No	Two-letter US state code — provide this or q
limit	integer (1–25, default 10)	No	Rows to return

curl -s -X POST https://www.byway.world/api/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_destinations","arguments":{"q":"Bozeman"}}}'

Example result: Found 1 destinations: - Bozeman, Montana — 4 byways · 2 national parks · 6 campgrounds within 30 mi — https://www.byway.world/destinations/bozeman-montana Byways within 30 mi of Bozeman: Paradise Valley Scenic Byway (12 mi) · ...

places_along_route

Places along a route

OAuthRead-only

Param	Type	Required	Description
origin	string	Yes	Where the drive starts (city or place name)
destination	string	Yes	Where it ends (city or place name)
kind	enum (place kind)	No	Place type to filter on
bandMi	number	No	Miles either side of the corridor
limit	integer	No	Rows to return

curl -s -X POST https://www.byway.world/api/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H 'authorization: Bearer <your-oauth-token>' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"places_along_route","arguments":{"origin":"Bozeman, MT","destination":"West Yellowstone, MT","kind":"waterfalls"}}}'

Example result: 3 atlas places along Bozeman, Montana to West Yellowstone, Montana (2 on the road itself). - ...

Version history

v1.7.02026-08-18

Every tool now advertises whether it needs sign-in (securitySchemes), and a gated tool refused for an expired token returns a challenge a host can act on instead of a dead-end error. No tool added or removed.

v1.6.02026-08-18

Server description refreshed for the category flip. No tool-surface change.

v1.5.02026-08-17

search_destinations ships (brief 31) — 10 tools.

v1.4.02026-08-16

search_byways reports total/truncated on a capped page. plan_drive gains budget_min and depart_at. Places carry verdictDetail, headliner, and an operational block (openingHours, condition, dwellMin).

v1.3.02026-08-11

The atlas ships over MCP: search_places, get_place, places_on_byway, and the OAuth-gated places_along_route. Every place result carries a citable url; the two corridor tools report distanceFromRouteMi. 9 tools.

v1.2.02026-08-10

Every lookout result carries a citable url to its own byway.world page.

v1.1.02026-08-03

Tool-surface vocabulary normalized to one noun.

v1.0.02026-07-11

Initial publish — search_byways, get_byway, search_lookouts, get_itinerary.

This page is generated from the live tool registry — every tool, schema and version above reads directly from the code that runs at https://www.byway.world/api/mcp. Looking for the consumer pitch instead? See Byway in ChatGPT & Claude.