MCP tool reference

Read-only tools, accepted arguments and response handling for Movies, releases, Venues and schedules.

All 20 tools below are read-only. This reference is generated from the server's registered tool definitions. Your MCP client can retrieve the same names and argument schemas using tools/list; available data still depends on your grant. Connection and authentication instructions →

Download tool definitions (JSON) ↓. This is a build-time reference, not an MCP endpoint or an OpenAPI document.

Unknown arguments are rejected. Treat IDs and cursors as opaque strings returned by the service. The downloadable schemas include exact string-length and format constraints.

Results and errors

Successful calls return a JSON text block in content and the same object in structuredContent. Item tools return data and meta. Lists also return page.nextCursor and page.hasMore. Stop when the cursor is null. An empty list is a successful response, not a service error.

Illustrative structuredContent · empty list, not live data

{
  "data": [],
  "page": {
    "nextCursor": null,
    "hasMore": false
  },
  "meta": {
    "requestId": "example-request-id",
    "generatedAt": "2026-09-08T00:00:00.000Z"
  }
}

Authentication, Origin and request-limit failures can reject the HTTP request before MCP runs. A tool failure sets isError: true; inspect content even if HTTP succeeded. Data-service failures include a JSON text block with error.status, error.detail and meta.requestId. Protocol and argument errors can instead be JSON-RPC errors or SDK validation text; do not assume every error has that JSON shape.

Correct invalid inputs and access problems before retrying. Retry transient service failures with bounded backoff, and retain the request ID. Missing or inaccessible items return a tool error, not an empty list. See HTTP errors and retries for the shared API boundary.

Data fields match the corresponding REST reads: Movies, releases, distributors, markets, operators, Venues and auditoriums, and showings and availability. get_access returns data.access (scopes, country codes, mode and operator ID) and data.limits (page size and schedule range), plus meta.

`list_country_releases`

List country Releases (whole theatrical runs) by Movie and current/archived/all scope. Defaults to current. IDs and detail URLs survive archival. Returns one page; pass nextCursor as cursor for more.

Argument	Type	Details
`limit`Optional	`integer`	Default: 50 · Minimum: 1 · Maximum: 100
`cursor`Optional	`string`	Opaque cursor from the previous response. Preserve the same filters.
`countryCode`Optional	`string`	Optional two-letter country filter. This narrows results; it does not grant access.
`movieId`Optional	`string`	Public canonical movie identifier (mov_…).
`scope`Optional	`string`	Defaults to current (D1-owned). Archived selects published history; all explicitly combines both. Ownership is independent of Showing or premiere dates. Archived/all requires history:read. · Values: current, archived, all

`list_markets`

List covered city markets; countryCode narrows granted access. Returns one page; pass nextCursor as cursor for more.

Argument	Type	Details
`limit`Optional	`integer`	Default: 50 · Minimum: 1 · Maximum: 100
`cursor`Optional	`string`	Opaque cursor from the previous response. Preserve the same filters.
`countryCode`Optional	`string`	Optional two-letter country filter. This narrows results; it does not grant access.

`list_operators`

List Venue operating organizations in the permitted countries and markets. Returns one page; pass nextCursor as cursor for more.

Argument	Type	Details
`limit`Optional	`integer`	Default: 50 · Minimum: 1 · Maximum: 100
`cursor`Optional	`string`	Opaque cursor from the previous response. Preserve the same filters.
`countryCode`Optional	`string`	Optional two-letter country filter. This narrows results; it does not grant access.

`list_venues`

Find Venues by market or operator. Use returned IDs to query their schedules. Returns one page; pass nextCursor as cursor for more.

Argument	Type	Details
`limit`Optional	`integer`	Default: 50 · Minimum: 1 · Maximum: 100
`cursor`Optional	`string`	Opaque cursor from the previous response. Preserve the same filters.
`countryCode`Optional	`string`	Optional two-letter country filter. This narrows results; it does not grant access.
`marketId`Optional	`string`	Public market identifier (mkt_…).
`operatorId`Optional	`string`	Public operator identifier (opr_…).

`list_distributors`

List theatrical distributors in the permitted countries. Returns one page; pass nextCursor as cursor for more.

Argument	Type	Details
`limit`Optional	`integer`	Default: 50 · Minimum: 1 · Maximum: 100
`cursor`Optional	`string`	Opaque cursor from the previous response. Preserve the same filters.
`countryCode`Optional	`string`	Optional two-letter country filter. This narrows results; it does not grant access.

`list_releases`

Find theatrical release announcements by country, distributor and release-date window. Scope defaults to current; use archived or all for history. Dates can change; this is collected calendar data, not a guarantee of release or rollout. Returns one page; pass nextCursor as cursor for more.

Argument	Type	Details
`limit`Optional	`integer`	Default: 50 · Minimum: 1 · Maximum: 100
`cursor`Optional	`string`	Opaque cursor from the previous response. Preserve the same filters.
`scope`Optional	`string`	Defaults to current (D1-owned). Archived selects published history; all explicitly combines both. Ownership is independent of Showing or premiere dates. Archived/all requires history:read. · Values: current, archived, all
`countryCode`Optional	`string`	Optional two-letter country filter. This narrows results; it does not grant access.
`distributorId`Optional	`string`	Public distributor identifier (dst_…).
`releasesFrom`Optional	`string`	Inclusive local release date, YYYY-MM-DD. Format: date
`releasesBefore`Optional	`string`	Exclusive local release date, YYYY-MM-DD. Format: date

`search_movies`

Search the collected canonical Movie catalog by title and production year. This does not search upstream providers or start ingestion. Returns one page; pass nextCursor as cursor for more.

Argument	Type	Details
`limit`Optional	`integer`	Default: 50 · Minimum: 1 · Maximum: 100
`cursor`Optional	`string`	Opaque cursor from the previous response. Preserve the same filters.
`query`Optional	`string`	Case-insensitive substring of the title or original title.
`releaseYear`Optional	`integer`	Filter by the original release year. Minimum: 1880 · Maximum: 2200

`get_country_release`

Get one country Release and its current/archived ownership. This is a run, distinct from a calendar announcement.

Argument	Type	Details
`id`Required	`string`	Public resource identifier returned by the API. Opaque Box Observer ID returned by a list tool.

`get_market`

Get a covered city market.

Argument	Type	Details
`id`Required	`string`	Public resource identifier returned by the API. Opaque Box Observer ID returned by a list tool.

`get_operator`

Get a Venue operating organization.

Argument	Type	Details
`id`Required	`string`	Public resource identifier returned by the API. Opaque Box Observer ID returned by a list tool.

`get_venue`

Get a Venue and its location and operator.

Argument	Type	Details
`id`Required	`string`	Public resource identifier returned by the API. Opaque Box Observer ID returned by a list tool.

`get_distributor`

Get a theatrical distributor.

Argument	Type	Details
`id`Required	`string`	Public resource identifier returned by the API. Opaque Box Observer ID returned by a list tool.

`get_release`

Get a collected theatrical release announcement.

Argument	Type	Details
`id`Required	`string`	Public resource identifier returned by the API. Opaque Box Observer ID returned by a list tool.

`get_movie`

Get canonical Movie information by its Box Observer ID.

Argument	Type	Details
`id`Required	`string`	Public resource identifier returned by the API. Opaque Box Observer ID returned by a list tool.

`get_showing`

Get one Showing, including source freshness and available price/seat observations. Public seat availability is not confirmed bookings or revenue.

Argument	Type	Details
`id`Required	`string`	Public resource identifier returned by the API. Opaque Box Observer ID returned by a list tool.

`list_release_showings`

Read Showings for one country Release ID, automatically following its current or archived ownership. No date window is required; optional dates narrow the result. History permission is required after archival.

Argument	Type	Details
`limit`Optional	`integer`	Default: 50 · Minimum: 1 · Maximum: 100
`cursor`Optional	`string`	Opaque cursor from the previous response. Preserve the same filters.
`venueId`Optional	`string`	Public venue identifier (ven_…).
`movieId`Optional	`string`	Public canonical movie identifier (mov_…).
`operatorId`Optional	`string`	Public operator identifier (opr_…).
`marketId`Optional	`string`	Public market identifier (mkt_…).
`countryCode`Optional	`string`	Optional two-letter country filter. This narrows results; it does not grant access.
`localDate`Optional	`string`	Cinema-local calendar date, YYYY-MM-DD. Cannot be combined with timestamp bounds. Format: date
`startsFrom`Optional	`string`	Inclusive start timestamp. ISO 8601; offsets are normalized to UTC. Format: date-time
`startsBefore`Optional	`string`	Exclusive end timestamp. The schedule window is limited to 31 days. Format: date-time
`id`Required	`string`	Public resource identifier returned by the API. Opaque Box Observer ID returned by a list tool.

`list_showings`

List Showings by Movie, Venue, market, operator or country. Use localDate OR a UTC startsFrom/startsBefore window (maximum 31 days). Defaults to current scope and the upcoming window. Use scope=archived or all with explicit dates for historical analysis. Public availability is not confirmed bookings. Results are paginated.

Argument	Type	Details
`limit`Optional	`integer`	Default: 50 · Minimum: 1 · Maximum: 100
`cursor`Optional	`string`	Opaque cursor from the previous response. Preserve the same filters.
`scope`Optional	`string`	Defaults to current (D1-owned). Archived selects published history; all explicitly combines both. Ownership is independent of Showing or premiere dates. Archived/all requires history:read. · Values: current, archived, all
`releaseId`Optional	`string`	Public country Release identifier (crl_…).
`venueId`Optional	`string`	Public venue identifier (ven_…).
`movieId`Optional	`string`	Public canonical movie identifier (mov_…).
`operatorId`Optional	`string`	Public operator identifier (opr_…).
`marketId`Optional	`string`	Public market identifier (mkt_…).
`countryCode`Optional	`string`	Optional two-letter country filter. This narrows results; it does not grant access.
`localDate`Optional	`string`	Cinema-local calendar date, YYYY-MM-DD. Cannot be combined with timestamp bounds. Format: date
`startsFrom`Optional	`string`	Inclusive start timestamp. ISO 8601; offsets are normalized to UTC. Format: date-time
`startsBefore`Optional	`string`	Exclusive end timestamp. The schedule window is limited to 31 days. Format: date-time

`list_auditoriums`

List auditoriums for a Venue ID. Results are paginated.

Argument	Type	Details
`limit`Optional	`integer`	Default: 50 · Minimum: 1 · Maximum: 100
`cursor`Optional	`string`	Opaque cursor from the previous response. Preserve the same filters.
`id`Required	`string`	Public resource identifier returned by the API. Opaque Box Observer ID returned by a list tool.

id is the Venue ID, not an auditorium ID.

`get_availability_history`

Read paginated seat-availability observations for a Showing ID, with observation times. Unavailable seats are not authoritative bookings; missing observations are not zero demand.

Argument	Type	Details
`limit`Optional	`integer`	Default: 50 · Minimum: 1 · Maximum: 100
`cursor`Optional	`string`	Opaque cursor from the previous response. Preserve the same filters.
`id`Required	`string`	Public resource identifier returned by the API. Opaque Box Observer ID returned by a list tool.

id is the Showing ID. This tool returns a page of observations, not a single item.

`get_access`

Inspect your permitted scopes, countries, market restriction and request limits. Filters never expand these grants.

No arguments. Send an empty object or omit arguments.