Vivu MCP reference: authentication, requests, responses, limits, errors.

Authentication

Every call runs inside an authenticated session. vivu_sign_in establishes it against a Vivu account; the session carries an expiry and must be re-established when it lapses. vivu_status is the check: it reports whether the client is configured, whether the session is valid, and whether the backend is reachable.

vivu_status()

{
  "auth":    { "configured": true, "signed_in": true, "expires_at": 1786673020553 },
  "backend": { "ok": true, "runtime": "production" }
}

There is no anonymous access. An unauthenticated caller cannot list projects, index, or search.

Reading local files is a second permission, granted per folder with vivu_grant_directory_access and listable and revocable with vivu_list_directory_access and vivu_revoke_directory_access. Signing in does not grant file access.

Projects and scope

A project is the unit of scope. Indexing puts material into one project and a search runs inside one project — there is no cross-project search. Use vivu_list_projects to find one and vivu_create_project to make one.

Indexing: request and status

Indexing is asynchronous. The index call returns a batch id straight away; progress is read separately. A file is searchable when its indexing finishes, not when its upload does — the two are reported as different things on purpose.

vivu_index_folder({ folder: "/Volumes/Media/2026-q3", project_id: "prj_q3" })
// or a specific list
vivu_index_files({ files: ["/Volumes/Media/2026-q3/all-hands.mp4"], project_id: "prj_q3" })

{ "batch_id": "bat_31ac9" }

vivu_get_upload_batch({ batch_id: "bat_31ac9" })

{
  "batch_id": "bat_31ac9",
  "upload":   { "completed": 4, "total": 6 },
  "indexing": { "completed": 2, "in_progress": 2, "failed": 0 }
}

vivu_get_job and vivu_get_jobs report the status and progress of a single indexing or refinement job.

Search: request and response

vivu_search_videos takes a plain-language query, a project, and a mode.

In precise mode the call returns a search id, then vivu_get_search_results is called repeatedly with the same id until complete is true. Each call waits and reports progress rather than returning a partial ranking.

vivu_get_search_results({ search_id: "srch_8f21c4", wait_seconds: 45 })

// still working
{ "complete": false, "progress": { "stage": "refining", "done": 12, "total": 40 } }

// finished
{
  "complete": true,
  "results": [
    {
      "source_id":    "vid_4a19",
      "source_title": "q3-all-hands.mp4",
      "start_ms":     754000,
      "end_ms":       791000,
      "evidence":     "spoken: \"...from October the tiers collapse into two...\"",
      "why":          "Direct statement of the pricing change by the speaker on screen."
    }
  ],
  "result_page": "https://<vivu-result-page>/s/…"
}

Opening a moment

vivu_get_preview_links creates short-lived playable links for chosen results. They stream the moment; they are not downloads and not exports. Exporting local clips is a separate call, vivu_export_results, and is confirmed by the user first.

Limits

• One project per search; no cross-project queries.
• Precise search is asynchronous and must be polled to completion.
• Only explicitly authorised directories can be read.
• Indexing and upload are reported separately; do not treat a completed upload as searchable.
• The public one-video trial on /try has its own, tighter caps and does not go through MCP.

Errors

Direct HTTP access

The MCP server is the documented developer surface. The HTTP service behind it is internal and not published: it has no anonymous access and no public stability guarantee, so integrating against it directly is arranged with Vivu rather than reverse-engineered. Contact sales if a direct integration is what you need.