MCP docs

Padel Near You MCP server

A public, read-only Model Context Protocol server for the games and venues published on this site. To connect an app step by step, see Use with AI.

Connect

https://padelnearyou.com/mcp

Transport: Streamable HTTP, stateless. Each request is one JSON-RPC POST; replies are JSON. A GET answers 405.
Authentication: None. Everything returned is already public on this site.
Capabilities: Four read-only tools and one UI resource (MCP Apps). No prompts, no sampling, no writes.
Version: padel-near-you 1.2.0

Tools

`padel_near_you_list_cities`

Cities with their exact slugs, time zones, board links and coverage. No arguments.

`padel_near_you_search_games`

Upcoming games in one city, filtered like the board. Results are sorted by date and start time and paged; see search choices.

`padel_near_you_get_game`

One game by city and its exact id from a search, including cancelled or past games. Never substitutes another game.

`padel_near_you_render_games`

Shows up to 20 games as visual cards in apps that support MCP Apps. Takes city and ids (unique exact ids from search or get). Unknown ids fail the whole request; full or cancelled open matches are left out. Apps without card support receive the same data as text.

Search choices

Only city is required. Dates and times are the city’s local time.

Choice	Values	Default and meaning
`city`	slug, e.g. `canggu`	Required. From `padel_near_you_list_cities`.
`date_from`, `date_to`	`YYYY-MM-DD`	Today through 30 days ahead, inclusive. Must ascend.
`start_time_from`, `start_time_to`	`HH:MM`	Start time window. Must ascend; an overnight window needs two searches.
`level_band`	`beginner`, `improver`, `intermediate`, `upper-intermediate`, `advanced`, `expert`	Any level. Games with an unknown level are left out of a level search.
`event_type`	`club-social`, `player-match`, `competition`, `other-event`	All types.
`gender`	list of `men`, `women`, `mixed`	Everyone. Games without a stated gender stay in; a game’s explicit eligibility decides. For games with separate categories, gender is matched per category and `level_band` on the game as a whole.
`open_matches`	`true` or `false`	`true`: open matches are included, like the board’s “Open games” switch.
`training_sessions`	`true` or `false`	`false`: lessons are hidden unless asked for, like the board.
`availability`	`all`, `open`, `full`, `unknown`	`all`. Based on the last recorded spots, not a live guarantee.
`page_size`	1 to 50	20.
`cursor`	`nextCursor` from the last page	Keep every other choice the same. If the published data changed, start again without a cursor.

Full open matches are never listed. An empty result means nothing published matches, not that no games exist.

Cards and alerts

Each game includes sourceUrl (the club’s own booking or listing page, when verified), boardUrl (the city board) and alertUrl.

alertUrl opens this site with the alert sign-up ready for that game: email me when it repeats, or when similar games appear. The person types and confirms their email on padelnearyou.com, so an assistant should share the link and never ask for an email address. The cards show it as a Get alerts button.

The card resource is ui://padel-near-you/event-cards-v1 (text/html;profile=mcp-app). It loads nothing from the network and opens links only through the host.

Data rules

Games are published observations from public club listings, with checkedAt and source check times. Confirm with the club before travelling.
Levels are approximate discovery bands, not official ratings. The original wording stays in nativeLevel.
Unknown facts are null, never guessed. The server never books, pays or contacts clubs.
Plain-text overviews for language models: llms.txt and ai-guide.md.

Limits

120 requests a minute across all clients and 8 at a time; above that the server answers 429 with Retry-After.
Requests up to 64 KiB, replies up to 256 KiB, 10 seconds each. Use a smaller page_size if a reply is too large.