API DOCUMENTATION / EVENTS CONNECTOR
Events connector
Find upcoming public events in large U.S. cities.
What it is
Find upcoming public events in large U.S. cities (San Francisco, Los Angeles, New York, Chicago, Denver, San Diego, Austin, Dallas, Houston and more): concerts and club nights, community meetups, arts events and free museum days. Search by city or a point on the map, a date window (tonight, tomorrow, this weekend, the next 7 days), keyword, category and whether it is free, or count what's on by category. Listings come from public calendars such as 19hz, Funcheap SF, DICE, Luma and Partiful; each event links to its source page, so check times and tickets there before you go. Listings from sites whose terms forbid reuse are not included. Preview data: coverage is partial and fields may change. Every record links to its sources; check anything important at the source.
Connect
Endpoint: https://events-mcp.headcountlabs.com/mcp/public/events. It uses Streamable HTTP, is stateless and takes POST requests only. No account or key is needed. The data is read-only and U.S. only.
Example prompts
- Free things to do in San Francisco this weekend.
- House music events in Chicago in the next 7 days.
- What's on tonight near the Mission District in San Francisco?
- What's on tonight within 2 km of the Mission District in San Francisco?
- How many events are on in Los Angeles this weekend, and what kinds?
Tools
These are the tools the endpoint returns from tools/list. A * marks a required input.
| Tool | What it does | Inputs |
|---|---|---|
find_events | Find public events (city parks and culture events, library programmes, council meetings, university calendars), soonest first. | lat, lon, radius_m, walk_minutes, city, when, from, to, tz, is_free, category, q, place_id, limit, cursor, fields |
get_event | One event by UUID (from find_events): title, start and end, venue with coordinates and place link, free or price range, categories, organizer, ticket or info URL, a description excerpt, and the recurring series it belongs to. | id*, fields |
get_event_series | A recurring event (weekly story time, a market, a class) by its series UUID (series_id from get_event): title, venue, and its next scheduled occurrences. | id*, limit, fields |
event_counts | Count upcoming events in a city or near a point in a window (when, or from/to): total, free, top 20 categories and per local day. | lat, lon, radius_m, city, when, from, to, tz |
get_event_record | The full stored record of one event by its UUID (the id returned by find_events or get_event): every field with the source it came from. | id* |
get_event_series_record | The full stored record of one recurring event series by its UUID (the id returned by the series_id of get_event): every field with the source it came from. | id* |
Every tool only reads public records and changes nothing. Pages hold at most 100 items, 20 by default. fields trims each item. Record IDs are for follow-up calls only.
Limits
Rate limits: 20 tool calls per minute per conversation (ChatGPT openai/session or the Mcp-Session-Id issued at initialize) and 600 requests per minute per network; over the limit, a tool call returns isError with the wait time and HTTP requests get 429 with Retry-After.
Responses are capped at 60,000 characters (items trimmed from the end, meta.truncated set).
Errors
A failed call returns an MCP tool result with isError: true and the API error JSON (invalid_parameter 400 naming the parameter, not_found 404, invalid_cursor 400, query_timeout 503 asking for a narrower search, read_only 503). Unknown tools and record paths outside this index are refused with a message. JSON-RPC errors: -32700 parse error, -32601 unknown method. HTTP 405 for GET/DELETE, 413 over 256 KB.