# Tavern Finder — full agent guide

Companion to <https://tavernfinder.com/llms.txt>, which is the spec-shaped
index. This file holds the detail that does not fit the llms.txt format
(tables, config snippets, prose).

Tavern Finder is a directory and event-booking platform for tabletop gaming
venues — game stores, cafes, hobby centers, and community spaces. It indexes
Magic: The Gathering, Disney Lorcana, Pokémon, Flesh and Blood, Warhammer,
board games and RPG sessions across 16,900+ venues worldwide, with 267,000+
upcoming events.

## How to use Tavern Finder from an AI agent

Three options, in order of preference.

### 1. Native MCP (recommended)

Point an MCP client at `https://mcp.tavernfinder.com/mcp` (Streamable HTTP
transport). No install. Six tools:

| Tool             | Auth needed               | What it does |
|------------------|---------------------------|---|
| `search_events`  | none                      | Find upcoming events near a lat/lng, optionally filtered by BGG ID and type |
| `search_venues`  | none                      | Find venues by name, city, type, amenities, products |
| `search_games`   | none                      | Look up BGG IDs for a game name |
| `rsvp_event`     | PAT, `write:rsvp`         | Join an event on the user's behalf |
| `register_user`  | none                      | Create a new account; returns access + refresh tokens |
| `create_event`   | PAT, `write:create_event` | Create an open event or table booking at a venue the user has access to |

Configure Claude Desktop:

```json
{
  "mcpServers": {
    "tavernfinder": {
      "url": "https://mcp.tavernfinder.com/mcp"
    }
  }
}
```

For write tools, add `"headers": {"Authorization": "Bearer tf_pat_..."}`.
Mint a token at <https://tavernfinder.com/profile/tokens>.

### 2. Public REST API

OpenAPI 3.0 spec: <https://tavernfinder.com/openapi.json>.
Human-readable docs: <https://tavernfinder.com/docs/api>.

Read endpoints need no authentication.

### 3. HTML + structured data

Every public page is server-rendered and emits schema.org JSON-LD: venues as
`LocalBusiness`, events as `Event`. `/sitemap.xml` is a sitemap **index**
pointing at 15 child sitemaps — one covering venues and static pages, fourteen
covering upcoming events — with hreflang alternates for `pt`, `en` and `es`.
Fetching the HTML directly is a valid strategy; no JavaScript execution is
required to read a venue or event page.

## Authentication for the write path

The user mints a personal access token at
<https://tavernfinder.com/profile/tokens>, picks the scopes they want to grant
(`write:rsvp`, `write:create_event`, `write:profile`), and pastes the token into
the agent's MCP config or any `Authorization: Bearer` header. Tokens are
revocable at any time on the same page.

## Rate limiting

Per-IP. Most agents will never reach the cap: 500 req/min globally, and
10 req/10s on `/activities/discover` and `/games-bgg`. High-volume service
providers should contact `keeper@tavernfinder.com` about an
`X-Internal-Service-Secret` arrangement that bypasses the limiter.

## More

Human-readable MCP guide with client setup, the full tool reference and sample prompts:
<https://tavernfinder.com/en/docs/mcp>