Skip to content
VividProp
Get started

MCP · Model Context Protocol · 2025-06-18

  • Claude
  • ChatGPT
  • Cursor
  • Claude Code
  • Codex

VividProp MCP.A studio your AI can call.

Claude, Cursor, Claude Code, Codex or a hosted agent can read the catalogue, import a listing, add the photographs and queue the render. The queue, the organisation scope and the credit ledger stay on our side.

Get early access REST API reference

10 workspace tools · stateless Streamable HTTP · bearer key, no OAuth · no credit movement

01 · The endpoint

Add the server

Transport Streamable HTTP. One header, no session id, no OAuth flow.

https://app.vividprop.ai/api/mcp

Authorization: Bearer vp_live_…

02 · The key

Mint it, scope it, revoke it

Settings → API keys. Scopes projects:write and jobs:read. Shown once, expiring by default, revoked in one click.

The key row supplies the organisation. No tool accepts an organisation id.

03 · The first call

Ask for the status first

vividprop_status returns every capability with its status and evidence, so the assistant cannot describe an unshipped feature as available.

A tool outside the key’s scopes answers exactly like an unknown one.

Connect your assistant

Five clients, one endpoint

Every client below talks to the same ten tools with the same bearer key. ChatGPT's web UI is the exception it admits to: it cannot send a static key, so its card gives the two honest paths instead.

  • Claude logoClaude

    Claude web, Desktop and Cowork

    1. Open Customize → Connectors → Add → Add custom connector.
    2. Paste https://app.vividprop.ai/api/mcp as the server URL.
    3. Under Request headers add Authorization with the value Bearer vp_live_… (your key, shown once).
    4. Enable it per conversation from the + menu → Connectors.

    Connections come from Anthropic's cloud, so the public endpoint is reachable; editing a connector means removing and re-adding it.

    Anthropic custom connectors Claude connectors settings

  • ChatGPT logoChatGPT

    ChatGPT web

    1. ChatGPT's custom MCP servers accept OAuth or no authentication only — they cannot send your static bearer key, so the hosted endpoint cannot be added there directly.
    2. Honest path one: run the Codex guide below — same account family, same key.
    3. Honest path two: expose the REST API (/api/v1) as a Custom GPT Action with its API-key auth. OpenAI treats Actions as the legacy route toward plugins.

    Never paste the key into a URL query string outside personal testing.

    OpenAI custom MCP servers ChatGPT plugins

  • Cursor logoCursor

    Cursor editor

    1. Open Cursor Settings → MCP → New MCP server, or edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (project).
    2. Add the server with a headers entry — no OAuth needed — then toggle it on.
    {
  "mcpServers": {
    "vividprop": {
      "url": "https://app.vividprop.ai/api/mcp",
      "headers": { "Authorization": "Bearer vp_live_…" }
    }
  }
}

    Cursor docs

  • Claude Code logoClaude Code

    Claude Code CLI

    1. Run one command — the key travels as a header, never through OAuth:
    2. Verify with claude mcp list; add --scope project to share the server through .mcp.json.
    claude mcp add --transport http vividprop https://app.vividprop.ai/api/mcp \n  --header "Authorization: Bearer vp_live_…"

    Claude Code MCP reference

  • Codex logoCodex

    Codex CLI, IDE extension and ChatGPT desktop app

    1. Edit ~/.codex/config.toml (shared by the CLI, the IDE extension and the desktop app):
    2. Export VIVIDPROP_API_KEY with your vp_live_… key in the shell that launches Codex.
    [mcp_servers.vividprop]
url = "https://app.vividprop.ai/api/mcp"
bearer_token_env_var = "VIVIDPROP_API_KEY"

    OpenAI MCP docs Codex MCP config reference

Client names and logos belong to their owners; menu labels change, so the linked docs are canonical. The key is shown once in Settings → API keys — if it leaks, revoke it and mint another. Freebuff's own advertiser MCP guide lives at freebuff.com/docs/advertisers/mcp.

One conversation, one queued render

From prompt to film

The assistant does the parts that are typing: paste the listing, pick the photographs, ask for the ratio. The cut itself is made by the worker that makes every other film, from the plan the project already holds.

Interface preview

Tool calls as an MCP client renders them

  • YouImport this listing, add the eight photographs, and cut a silent 9:16 film for Reels.
  • Toolvividprop_import_listing → 8 photographs found · 0 credits
  • Toolvividprop_create_project → projectId 7c41… · 9:16 · 30 s
  • Toolvividprop_import_photos → 8 assets stored · EXIF stripped
  • Toolvividprop_render_film → job 9a2f… queued
  • AssistantQueued. The worker holds it; I will poll vividprop_job_status.

Illustrative values, not a customer record. Every tool shown is listed by the live endpoint; the ids are placeholders.

A cliffside villa living room at blue hour, seen from inside toward the sea — AI-generated VividProp brand imagery, not a customer property
AI-generated brand imagery — not a customer property, and not a rendered export.

One worker, no second renderer

Every tool calls the same /api/v1 route the product and the CRM use. Same validation, same organisation scope, no MCP-only path to drift.

The key is the workspace

Nothing in a call names an organisation. A foreign project id answers 404 not_found, not another workspace's row.

A failure is a result

A refused render returns isError with its code — NO_SCENES, SCENES_NOT_READY, a 401 — never an invented success.

Ten tools, two scopes

What the assistant can actually do

The list below is the hosted endpoint’s whole surface. If a tool is not here, no prompt makes it exist.

  • vividprop_status

    Every capability with its status and evidence, plus the counts per status.

    jobs:read

  • vividprop_list_projects

    The workspace's projects: id, title, status, aspect ratio, target length.

    jobs:read

  • vividprop_project_detail

    One project's scenes, its recent jobs and its newest render.

    jobs:read

  • vividprop_import_listing

    A zero-credit preview of a listing URL: facts and photograph URLs, nothing stored.

    projects:write

  • vividprop_create_project

    A property and its first project inside the key's workspace.

    projects:write

  • vividprop_import_photos

    One to five public image URLs, downloaded and EXIF-stripped server-side.

    projects:write

  • vividprop_generate_scene

    Queues a cinematic AI motion job for one scene and returns its catalogue estimate. No supervised paid run has completed, so no customer clip exists yet.

    projects:write

  • vividprop_render_film

    Queues the Fidelity export with the same guards as the product button.

    projects:write

  • vividprop_job_status

    The job, its failure code, and the newest successful export.

    jobs:read

  • vividprop_property_analytics

    Counted views, plays, completions, scans and enquiries. Zeros mean untracked.

    jobs:read

No scene reordering, no caption editing, no key management, no publishing and no credit movement through MCP.

The same workspace, over HTTP

When you would rather call it yourself

The REST API is what the assistant calls underneath: the same routes, the same organisation scope, the same key. It exists for a CRM, a portal integration or a script that has no MCP client.

Base URL

https://app.vividprop.ai/api/v1

Authorization: Bearer vp_live_…

  • Projects and properties. Create a project, read its scenes and its ordered photographs.
  • Photographs. Import public image URLs — downloaded, EXIF-stripped and re-encoded server-side — or upload through the signed path the app uses.
  • Renders. Queue the Fidelity export and poll the job until it succeeds, fails or is cancelled, with the failure code on the row.

First request

curl https://app.vividprop.ai/api/v1/projects \
  -H "Authorization: Bearer vp_live_…"
  • A missing or revoked key answers 401; a key without the scope answers like an unknown route.
  • No call names an organisation: the key row supplies it, and a foreign project id answers 404.
  • Reads move no credits; the render path reserves, commits and releases exactly as the app does.

The endpoint list, scopes and error codes are on this page because they are the same surface as the tools above: one key, one workspace, one worker. There is no second renderer behind the API.

Two servers, one contract

Hosted, or on your machine

The endpoint is for clients that cannot start a process. The stdio server is for editors that can — and it carries the catalogue reads the endpoint does not.

Remote

Streamable HTTP, stateless

POST https://app.vividprop.ai/api/mcp

  • MCP 2025-06-18 · ten tools · bearer key per request
  • No session id; a notification answers 202
  • For Composio, an Apify Actor or a hosted agent

Local

stdio, from a checkout

pnpm --filter @vividprop/marketing mcp
  • MCP 2024-11-05 · eleven tools · key passed per call
  • Five catalogue reads need no key at all
  • For Claude Desktop, Cursor, VS Code and the Codex CLI

ChatGPT’s web UI does not accept an arbitrary MCP server. Use the Codex CLI entry, or the documented OpenAPI schema as a Custom GPT Action with the same bearer key.

Questions, answered

Before you connect it

What can VividProp MCP actually do?

Ten workspace tools: read the capability status, list projects, read one project, preview a listing, create a project, import photographs, queue a cinematic motion job for one scene (it returns the catalogue estimate), queue the Fidelity render, poll the job, and read a property's counted analytics. The hosted endpoint exposes exactly those ten.

Do I need an API key?

Yes for anything that touches a workspace. Create a key in Settings → API keys with the projects:write and jobs:read scopes; it is shown once, expires by default and is revocable. The endpoint answers 401 without it, and tools/list only returns what the key's scopes allow.

Where does the server run?

Two places. The hosted server is POST https://app.vividprop.ai/api/mcp over Streamable HTTP for clients that cannot run a local process. The stdio catalogue server runs from a repo checkout with pnpm --filter @vividprop/marketing mcp for Claude Desktop, Cursor, VS Code and the Codex CLI.

Does a render spend credits?

No. vividprop_render_film queues the Fidelity export — FFmpeg moves over the photographs you supplied — and no credit ledger row is written. Credit purchase and settlement are not built. Paid cinematic generation has never run under supervision, so the available scene motion stays local, and a project with no usable photographs fails with its error code instead of a film.

Which clients are supported?

The transport is standard MCP. Step-by-step cards above: Claude via Connectors with a Request header, Cursor via mcp.json headers, Claude Code via --header, Codex via bearer_token_env_var. ChatGPT's web UI cannot send a static bearer key, so it connects through the Codex CLI entry or a Custom GPT Action over the REST API — never by pasting the key into a URL.

What does it deliberately not do?

It does not reorder scenes, edit captions, manage keys, publish to social networks or move money. A tool outside the key's scopes answers like an unknown tool, and a failure returns isError with the API's message — never a placeholder result.

The studio your AI was missing.

Ten tools, one workspace, and a film that is cut by the same worker as every other export. Nothing is simulated to make the demo shorter.

Get early access Read the REST reference