NearNow — MCP reference

NearNow is a read-only Model Context Protocol connector that answers "where can I get X nearby" for US places, with honest opening-hours confidence and OpenStreetMap attribution on every response.

Endpoint

Item	Value
MCP endpoint	`https://mcp.locafact.com/nearnow/mcp`
Transport	Streamable HTTP, `POST`, JSON-RPC 2.0 (stateless — no session id required)
Health check	`GET https://mcp.locafact.com/nearnow/healthz` → `{"ok":true,...}`
Server name / version	`nearnow` / `0.1.0`

⚠️ The /mcp suffix is required. A POST to /nearnow (without it) returns 404.

Authentication

NearNow is free with no account. Requests pass a review API key (issued on request, never expires, no MFA). Send it either way:

Authorization: Bearer <key>
X-API-Key: <key>

Missing or unknown key → 401 unauthorized.

Tools

search_places

Find nearby places from OpenStreetMap. Pass either a location or an area name. Each result includes distance, address, opening hours with hours_confidence, and open_now where determinable.

Parameter	Type	Required	Notes
`category`	string	yes	`pharmacy` · `supermarket` · `fuel` · `ev_charging` · `library` · `post_office`
`area`	string	one of area/location	e.g. `"Pasadena, CA"`
`location`	object `{lat,lng}`	one of area/location	lat −90..90, lng −180..180
`radius_m`	integer	no	100–20000
`open_now`	boolean	no	Keep only places likely open now. Unknown hours are excluded, never guessed.
`limit`	integer	no	1–10

hours_confidence: confirmed (from OSM data) · estimated (chain/category default) · unknown.

get_place_details

Full details for one place by its place_id (e.g. "osm:node/123") returned by search_places: exact coordinates, address, opening hours with confidence, contact info, and the OpenStreetMap URL.

Parameter	Type	Required
`place_id`	string	yes

list_categories

Lists the supported categories with an example query for each. No parameters. Call this if unsure which category value to pass.

Response statuses

Tool	`status` values
`search_places`	`OK` · `INVALID_INPUT` · `UNKNOWN_AREA` · `NO_MATCH`
`get_place_details`	`OK` · `INVALID_INPUT` · `NOT_FOUND`

A non-OK status is returned with isError: true and a human-readable message — never a fabricated answer. INVALID_INPUT also returns valid_categories.

HTTP error codes

Status	Body `error`	Cause
400	`invalid_json`	Malformed JSON body (or body > 1 MiB)
401	`unauthorized`	Missing / unknown API key
403	`origin_not_allowed`	`Origin` header present but not on the allow-list (browser origins like `localhost` are rejected; requests without an `Origin` header, e.g. curl/CLIs, are not origin-checked)
404	`not_found`	Unknown path (e.g. missing `/mcp`)
405	`method_not_allowed`	Non-POST on `/mcp` (returns `Allow: POST`)
429	`rate_limited`	Over 30 rps sustained / 60 burst per caller (returns `Retry-After: 1`)
500	`internal`	Unexpected server error

Quick start

curl -s https://mcp.locafact.com/nearnow/mcp \
  -H "Authorization: Bearer $NEARNOW_API_KEY" \
  -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":{"area":"Pasadena, CA","category":"pharmacy","limit":5}}}'

Latency disclosure

Frequently asked areas are pre-warmed and answer in under 100 ms. Uncached areas may take up to ~20 s on the first request while fresh map data is fetched; subsequent requests in the same area are fast.

Data & attribution

Read-only: NearNow never writes to OpenStreetMap or any other source.
No end-user personal data is collected; only a hashed client fingerprint for rate limiting.
Source code (MIT): github.com/applecore2002-sketch/nearnow

Support

Questions or issues: support@locafact.com (we reply within 48 hours).