WebMCP guide
VO Barna with your AI agent
Find an original-version screening around Barcelona, explore the film, and bring up its official ticket link. Your assistant can help through six tools that work alongside the page.
What you can do
- “Find science fiction in IMAX this weekend.”
- “Compare these films’ ratings and tell me who directed them.”
- “Show me that screening and its ticket link.”
- “Busca comedias para mañana.”
- “Mostra’m les sessions de dissabte.”
Search understands film titles, actors and other searchable credits, genres, languages, countries, cinemas, formats and date phrases in English, Spanish and Catalan. Language names also match production nationality: try espanol IMAX, catala or French tomorrow. An agent can compare returned film facts and ratings, then apply a search or open a particular screening for you to review.
Results depend on the collected programme. Examples illustrate requests you can make; they do not promise that matching screenings are available. Ticket selection and payment take place with the cinema.
The six tools
The tools are registered on the screenings page after its programme loads. Four read information. Two update the visible page and its shareable URL.
get_context
Reads informationDiscover the supported cinema IDs and formats, current filters, interface language, selected film or screening, programme coverage and collection timestamps. Dates are interpreted in Europe/Madrid.
Input: {}. Use this to learn what is available and understand the user’s current view.
search_screenings
Reads informationFind upcoming sessions without changing the page. Returns paginated screenings with exact film_id and screening_id values, cinema and room, dates and times, formats, cached availability, observed prices where known, and booking links.
Input: any of the search inputs, plus optional limit and offset. An empty object searches all upcoming collected sessions, independently of the page’s current filters.
{ "query": "Villeneuve this weekend", "formats": ["IMAX"], "limit": 10 }
Results include total_screenings, total_films, the resolved date range, a shareable search URL and next_offset. Sessions are ordered by start time, then screening ID. Use the same filters with next_offset to fetch the next page; null means there is no next page.
get_film
Reads informationRead collected film facts, credits, original languages, release information, runtime and ratings with their source links and observation dates. This includes details an assistant can use when comparing films.
Required input: film_id, copied from a search result. Film titles alone are not identifiers: different adaptations and double bills can be distinct entries.
get_screening
Reads informationInspect one session’s room, format, date, time, observed price and cached seat availability. Returns the official booking_url, its booking_scope, a VO Barna link and whether the screening has started.
Required input: screening_id, copied from a search result. This reads the shared cache; it does not make a fresh request to the cinema.
set_search
Updates the pageReplace the visible search and filters, close the film dialog, and update the results and URL. Structured filters appear as removable chips. Returns the first 20 matching sessions.
Input: any of the search inputs. Omitted filters are cleared. Pass {} to reset everything. Pagination arguments apply only to search_screenings.
{ "query": "comedia mañana" }
show_screening
Updates the pageOpen an upcoming session in the film dialog and highlight its official ticket link. If the current filters hide that session, the dialog shows the film’s upcoming sessions while preserving the underlying search.
Required input: screening_id, copied from a search result. The shareable URL leads to the film’s permanent page at the selected screening row. Opening the dialog does not reserve a seat, open checkout or purchase a ticket.
Search inputs
These inputs are shared by search_screenings and set_search. All are optional.
| Input | Meaning |
|---|---|
query | A string of up to 500 characters. Combine searchable words with natural dates, such as Villeneuve this weekend, comedia mañana or ciència-ficció dissabte. |
date_fromdate_to | Inclusive YYYY-MM-DD date bounds, or null. Use the same date for both to select one day. A single bound is open-ended. Explicit bounds override dates embedded in the query. |
cinema_ids | Up to 20 cinema IDs from get_context. A screening can match any listed cinema. An empty array means all cinemas. |
formats | Up to 20 format values from get_context. Every requested format must belong to the same screening. An empty array adds no format restriction. |
big_screens_only | A boolean, default false. Selects VO Barna’s curated premium selection, which includes comfort-focused venues. It is not a ranking by measured screen size. |
search_screenings additionally accepts limit (an integer from 1 to 50, default 20) and offset (an integer from 0 to 100000, default 0).
Relative dates use Barcelona’s calendar. Weeks run Monday–Sunday; a bare weekday means its next occurrence, including today. “In 2 weeks” selects a date 14 days ahead; “next 2 weeks” covers today and the following 13 days. Exact film titles and quoted phrases are protected from date parsing. Producer-only credits are excluded from search; other collected credits remain searchable.
From a request to a screening
- Read the context. Call
get_context({})for supported cinemas, formats and date coverage. - Find options. Call
search_screeningswith the user’s criteria. Follownext_offsetif you need more results. - Compare the details. Use returned IDs with
get_filmfor credits and ratings, orget_screeningfor a session’s cached availability and booking destination. - Show the choice. Use
set_searchto display a filtered programme, orshow_screeningto highlight the chosen session. - Continue with the cinema. The official ticket link leads to the cinema’s booking or event page. Seat selection, final availability, fees and payment are handled there.
Each returned url links back to VO Barna. Film links use permanent, language-specific paths such as /en/films/wicker-2026/; screening links add a stable #screening-… anchor. Search links use the current language’s listings page with query parameters. Use the URLs returned by tools rather than constructing a slug from a title or an anchor from a screening ID.
A booking_url points directly to the cinema’s provider and is independent of VO Barna’s slugs. Check booking_scope: an event-level link may still require choosing the date or session on the cinema’s site.
Try an ordinary shareable search: Villeneuve this weekend. The same page can be used manually, with or without an agent.
Understanding the data
- Coverage and freshness
- The programme covers collected listings at the cinemas returned by
get_context. A date with no matches may be unpublished or outside collected coverage. Use source collection timestamps and each session’sschedule_fetched_at; the overallprogramme_generated_atis not a fresh check of every provider. - Seat availability
- Counts are cached observations. Responses include
checked_at,age_seconds,stale,refresh_failedand provider support. A count is stale once it is older than the configured collection interval, available fromget_context. A refresh failure can leave an older count in place. - What a seat count means
- The
kindfield distinguishes ordinary seats, provider-reported totals and area counts. Wheelchair and companion spaces remain separate where supplied. Counts do not establish adjacent seats or reserve tickets. Status can bereported_available,sold_out,booking_closedorunknown; zero is not interpreted identically across count types. - Language and format
- VOSE means original audio with Spanish subtitles, not necessarily English audio. Film-level original languages and a session’s confirmed audio language are different facts. Use the session’s format tags; venue equipment does not guarantee a particular performance format.
- Prices and ratings
- Prices are observed session amounts where published, not a final checkout quote. Fees may apply. Ratings retain the publisher’s scale and observation date; critics’ and audience scores are separate. Unknown values remain unknown.
- Current limits
- The tools do not offer seat selection, reservations or payment. Time-of-day filters, rating-threshold filters, proximity searches and cinema/auditorium research are not part of the current tool inputs. Returned film facts and session times can still help an assistant compare options.
Access for agents and developers
This guide is static HTML. Its content, links and the JSON tool reference can be read without JavaScript, an account or a WebMCP-enabled browser. The JSON reference is generated from the implemented tool definitions and includes each tool’s description, input schema and annotations.
To execute tools, open the screenings page in a WebMCP-capable browser agent and allow its programme to load. VO Barna registers its tools through document.modelContext.registerTool(). Tools are available on the English, Spanish and Catalan listings pages. Direct film and cinema pages provide static details and ticket links; return to a listings page to execute tools. This guide does not register them. Tool names are in-page operations, not HTTP API routes; the JSON file is documentation, not an executable endpoint.
In a browser that supports discovery and execution through the current API, an example console call on the screenings page is:
const tools = await document.modelContext.getTools();
const search = tools.find(tool => tool.name === 'search_screenings');
await document.modelContext.executeTool(search, {
query: 'Villeneuve this weekend',
limit: 10
});
Tool results are JSON-serializable values. Successful operations return ok: true. Application failures use this shape:
{
"ok": false,
"error": {
"code": "not_found",
"message": "Screening not found in the current programme. Search again for its current ID."
}
}
Other error codes include invalid_input, not_ready, screening_started, cancelled and operation_failed. Unknown arguments and invalid IDs or dates are rejected before page changes. A cancellation received before execution makes no change.
The four information tools have readOnlyHint: true; the two page actions have readOnlyHint: false. All six mark their outputs with untrustedContentHint: true because they can include external cinema and film data. These annotations describe the tools; they are not access-control guarantees.
WebMCP and browser support are evolving. See Chrome’s WebMCP documentation, the WebMCP specification and the WebMCP directory for background. The regular VO Barna interface remains available when tools are unsupported.
