Agent integration guide

This page is written for the agent as much as for the developer wiring one up. It says which surface to use for which job, how each client connects, how a natural-language request maps onto a tool, and where the machine-readable contracts live.

Which surface to use

Every surface reads the same catalog; choose by how the caller works.

MCP: Tool-using agents and assistants. One streamable HTTP endpoint, 16 tools, free discovery, per-call payment inline.
REST: Applications, notebooks and scheduled jobs. Two endpoints dispatching on an action parameter, described by OpenAPI 3.1.
x402: Autonomous agents with a wallet and no account. Call either surface without a key, read the HTTP 402 requirements, pay, retry.
Web pages: Citations for people. Event, city, week, artist, venue and organizer pages on belong.events carry Event structured data and link to the box office.

Connect an MCP client

The endpoint is https://long.events/functions/v1/mcp-server/mcp for every client. initialize, ping and tools/list are free and need no key, so a client can verify the server before anything is configured.

Claude Code: claude mcp add long-events -t http https://long.events/functions/v1/mcp-server/mcp
Claude Desktop, Claude.ai and Claude apps: Settings → Connectors → Add custom connector with the URL https://long.events/functions/v1/mcp-server/mcp. No OAuth: discovery is anonymous, and an API key can be sent as the X-API-Key header where the client allows headers.
Cursor and VS Code: Add a streamable HTTP server named long-events with the URL https://long.events/functions/v1/mcp-server/mcp to the editor's MCP configuration.
OpenAI Responses API and Agents SDK: Pass a hosted MCP tool: { "type": "mcp", "server_label": "long_events", "server_url": "https://long.events/functions/v1/mcp-server/mcp" }.
Any other MCP client or framework: Streamable HTTP transport, JSON-RPC 2.0, POST https://long.events/functions/v1/mcp-server/mcp. Send initialize, then tools/list, then tools/call.
Plain HTTP, no MCP: GET https://long.events/functions/v1/api-events?action=discover&city=Lisbon&limit=20 with an X-API-Key header, or without one to receive x402 payment requirements.
OpenClaw skill: clawdhub install long-events installs the skill package whose source lives in the repository under long-events/.

From a request to a tool

Requests agents receive most often, and the first call that answers each one. Every tool returns venue, city, local time, organizer and ticket context, so a second call is rarely needed to act.

"What is on in Lisbon this weekend?": search_events with city, start_date and end_date; REST action discover with the same parameters.
"Techno parties near me tonight": search_events with latitude, longitude, radius_km, category and a one-day window.
"What is happening during Token2049 / ETH Denver / Devconnect?": search_event_weeks by name, then get_event_week_details for the full side-event programme.
"Which cities have a conference week next month?": get_event_week_cities, or get_event_weeks with upcoming set.
"When does Peggy Gou play next?": get_artist_events with the artist name and upcoming_only; search_artists when the spelling is uncertain.
"Who is on stage right now at the festival?": get_now_playing with the event_id or city.
"What time does ANOTR play?": get_event_schedule with the event_id or event_name; returns stages and set times in the venue clock.
"Best venues for electronic music in Berlin": get_venues with the city; each venue carries its upcoming programme.
"Who organizes crypto events in Lisbon?": search_organizers with a query, or search_events with category crypto and read the organizer field.
"Which cities have the most events?": get_cities, or the REST action catalog_stats.
"Full details and the ticket link for this event": get_event_details with the event_id; ticket_url is the resolved box-office path, not another listing site. Rank, predicted_end_time, and ticket_offer travel on the same payload.

Paying per call

A metered call without an API key returns HTTP 402 with x402 version 2 requirements: amount, asset, network and pay-to address. The standard lane is USDC on Base through a facilitator; self-facilitated ten-call bundles are available in USDT, USDC or USD1 on BNB Chain and in LONG. Over MCP the same payment travels in _meta["x402/payment"] on tools/call, and the settlement receipt comes back in the result. The default price is half a cent per call; api-pricing is authoritative.

Citing and linking

Cite the event page URL returned with each event for people, and ticket_url for the purchase path; both resolve to the organizer or box office rather than to another aggregator. Data is aggregated daily from primary sources and each record names its source, so an answer can say where the listing came from.

Machine-readable discovery documents

Everything an agent, crawler or directory needs in order to find and verify this API without reading HTML.

https://long.events/llms.txt: Short index of the documentation, endpoints and public routes.
https://long.events/llms-full.txt: The whole developer documentation in one plain-text file for retrieval and context windows.
https://long.events/openapi.json: OpenAPI 3.1 contract for the REST endpoints, pricing and discovery routes.
https://long.events/.well-known/mcp-server-card: MCP server card: identity, remote endpoint, protocol versions and optional headers.
https://long.events/.well-known/api-catalog: RFC 9727 API catalog linkset naming the contract, docs and pricing for every API anchor.
https://long.events/.well-known/x402: x402 discovery manifest: every payable resource with accepted schemes, networks, assets and prices.
https://long.events/functions/v1/mcp-server: Live MCP server status card: tools count, free methods and payment lanes.
https://long.events/functions/v1/api-pricing: Live per-action prices in USD and in each accepted asset.