# CityAlert.live — agent access

Preferred interface: the MCP server. It exposes the same data as the REST
API as typed tools, so agents don't need to hand-build GeoJSON queries.

## Machine interfaces

- MCP server (streamable HTTP, JSON-RPC 2.0): POST https://cityalert.live/api/mcp
  Alias for validators behind bot protection: https://cityalert.live/.well-known/mcp
  Methods: initialize, tools/list, tools/call, resources/*, prompts/list.
- OpenAPI 3.1 spec: https://cityalert.live/api/openapi.json
  Alias: https://cityalert.live/.well-known/openapi.json
- A2A agent card: https://cityalert.live/.well-known/agent-card.json
- MCP server card (Smithery static format): https://cityalert.live/.well-known/mcp/server-card.json
- llms.txt: https://cityalert.live/llms.txt — page map, incident field docs, live counts
- This file: https://cityalert.live/agents.txt — refetch it if cached >24h
- Human docs: https://cityalert.live/developers — endpoint reference, embeds
- REST base: https://cityalert.live/api — see the OpenAPI spec for every route

## Tools (MCP)

Free, anonymous:
  list_regions     focus-region keys/labels/bboxes — call this first
  get_incidents    GeoJSON incidents; filter by region, bbox, category,
                   severity, days (<=7), text query, source, limit
  get_news         regional safety headlines; ?place= for ad-hoc places
  get_dashboard    fetch a shared dashboard config by id
  submit_report    community incident report (rate-limited, reviewed)
  create_dashboard create a shareable dashboard; returns id + write token

Paid (Pro plan key):
  get_trends       historical aggregates — crime YoY, quakes, disasters
  get_crime_year   full-year incident GeoJSON + neighbourhood ranking

## Auth & limits

- Anonymous/free key: shared ~15-minute snapshot — responses
  carry meta.delayed. Don't poll faster than the snapshot cadence.
- Paid endpoints take an x-api-key: ca_... header.
  Developer ($99/mo): 5,000 req/day, /api/archive, days>7 on incidents.
  Pro ($499/mo): 50,000 req/day, MCP history tools, outbound webhooks.
- Keys are self-serve: https://cityalert.live/account (email sign-in → API keys).
- Errors: 401 missing/invalid key · 403 plan too low · 429 over the
  daily cap (Retry-After tells you when it resets, UTC midnight).

## House rules

- Use the API/MCP instead of scraping HTML pages — the map UI is a JS app,
  the data endpoints are faster, cheaper and complete.
- Respect robots.txt. Community report POSTs are IP rate-limited
  (5/hour reports, 30/hour votes) — don't automate them.
- Attribute CityAlert.live and the incident's `source` field when citing.
  Normalization layer is CC BY 4.0; upstream feeds carry their own
  licenses (https://cityalert.live/sources).
- Media-sourced incidents are approximate block-level locations —
  preserve that caveat when republishing.
- Aggregation/awareness tool only. For emergencies defer to official
  authorities.

Per-city Atom feeds: https://cityalert.live/cities/<slug>/feed.xml (20 latest).
Embed widget: https://cityalert.live/embed?city=<slug> — keep the credit link.