Wistia MCP Server

Search

search

Read-onlyIdempotent

Find Wistia folders, media, channels, webinars, and spoken-word transcript matches by query, tags, dates, or custom metadata.

Instructions

Searches across folders, subfolders, medias, channels, channel episodes, and webinars. Also searches through video transcripts, so media results may include transcript matches with timestamps when the query matches spoken content.

Requires api token with one of the following permissions

Read all data

Tokens with the "Act with a team member's permissions" permission (all:delegate_to_contact_permissions scope) can also be used. Requests made with such a token are authorized using the permissions of the contact assigned to the token. Read-only account operation.

Input Schema

TableJSON Schema

Name	Required	Description
`q`	Yes	The search query string
`tags`	No	Filter results by one or more tag names. When multiple tags are provided, results matching any of the specified tags are returned (OR logic).
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`include`	No	Pass `custom_metadata` to include each media result's custom metadata field values (same shape as the Get Custom Metadata Field Values endpoint). Only available on accounts with access to custom metadata (other accounts receive a 403 when this parameter is passed).
`created_after`	No	Filter results created on or after this datetime. Must be a valid ISO8601 timestamp in UTC (ending with 'Z').
`resource_type`	No	Filter results by one or more resource types.
`created_before`	No	Filter results created on or before this datetime. Must be a valid ISO8601 timestamp in UTC (ending with 'Z').
`custom_metadata`	No	Filter media by custom metadata field value, keyed by field key: `custom_metadata[<field_key>]=<value>`. Only available on accounts with access to custom metadata (other accounts receive a 403 when this parameter is passed). Custom metadata only exists on media, so results contain media only and `resource_type` must include `media`. Use an empty `q` to match all media. The value shape depends on the field's type: - Select, text, url, and email fields take a value (`custom_metadata[region]=emea`) or an array of values matched as OR (`custom_metadata[region][]=emea&custom_metadata[region][]=amer`). Select fields match on option keys. - Boolean fields take `true` or `false`. - Number, money, and time fields take an exact number (`custom_metadata[year]=2026`) or a range object (`custom_metadata[budget][min]=100&custom_metadata[budget][max]=500`; either bound may be omitted). - Date and datetime fields take a `YYYY-MM-DD` date matching that UTC day, or a range object with ISO8601 bounds (`custom_metadata[shoot_date][after]=2026-01-01`, `custom_metadata[shoot_date][before]=2026-02-01T00:00:00Z`). A bare-date bound covers its whole UTC day: `after` starts at the day's beginning and `before` runs through the day's end. - Contact fields (`contact_ref`, `contact_multi_ref`) only support the presence filter below; a value filter on them is rejected. - Any field type accepts a presence filter: `custom_metadata[region][exists]=false` returns media missing the field entirely (useful for metadata coverage audits), and `exists=true` returns media that have any value for it. Unknown or archived field keys return a 400, as do select option keys that don't exist on the field. The primary match set holds at most 100 media with no pagination; a non-blank `q` can add up to 100 more transcript-only matches, and an empty-`q` audit returns at most 100. Narrow large audits (e.g. with `created_after`/`created_before`) to complete full coverage.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv2.0.0Oct 2, 2026

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds genuinely new behavioral context: the required permission scope ('Read all data'), the delegation scope behavior ('Act with a team member's permissions'), and that results can include transcript matches with timestamps. This exceeds what the annotations convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first sentence, with transcript behavior immediately after and auth requirements last. The permission block is somewhat verbose but each part (scope name, delegation semantics) carries information an agent needs to call successfully.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-param tool with a nested object and no output schema, the description covers purpose and auth while the schema fully documents parameters and result limits. The main gap is that return shape (result ordering, mixing of transcript vs primary matches) is not described, though no output schema exists to carry it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, including a richly documented custom_metadata parameter with value shapes, error behavior, and 100-result limits. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (searches) and enumerates the exact resource types covered (folders, subfolders, media, channels, channel episodes, webinars), plus transcript content. This clearly distinguishes it as the unified cross-resource search entry point, though it never names the sibling list_*/find_* tools it overlaps with.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the enumerated searchable domains and the note that transcript matches carry timestamps, so an agent can infer when this applies. However, there is no explicit when-to-use vs alternatives guidance (e.g., versus list_media or find_caption_matches), and no exclusions or prerequisites beyond auth.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server