@prologue-ai/mcp

MCP (Model Context Protocol) server for Prologue AI. Lets AI agents generate images, video, audio, music, 3D, and more — using your org's credit balance.

Quick start

1. Get an API key

Open your org settings in Prologue (Settings > API Keys tab) and create a key. You'll see a key like sk-org-abc123... — copy it.

2. Add to your agent

Cursor — add to .cursor/mcp.json (use -y so npx does not prompt):

{
  "mcpServers": {
    "prologue": {
      "command": "npx",
      "args": ["-y", "@prologue-ai/mcp@latest"],
      "env": {
        "PROLOGUE_API_KEY": "sk-org-...",
        "PROLOGUE_BASE_URL": "https://prologue.ai"
      }
    }
  }
}

When installing from the Cursor Marketplace as a plugin, Cursor merges the bundled mcp.json from this package; set PROLOGUE_API_KEY (and optionally PROLOGUE_BASE_URL for local dev) in your environment or MCP UI.

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "prologue": {
      "command": "npx",
      "args": ["-y", "@prologue-ai/mcp@latest"],
      "env": {
        "PROLOGUE_API_KEY": "sk-org-..."
      }
    }
  }
}

Claude Code / any MCP client — same pattern: set the command and PROLOGUE_API_KEY env var.

Available tools

| Tool | Description | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | list_models | List available models. Filter by category (text-to-image, text-to-video, etc.) or search. | | get_model_schema | Get input fields for a model. Pass **model_ref** from list_models (opaque prg_… id). | | get_model_pricing | Estimated credits for a model (org pricing). Pass **model_ref. | | generate | Submit a job. Pass **model_ref** and input. Returns result or request_id for async jobs. | | enhance_prompt | Enhance or rewrite a prompt. Can generate scripts, strategies, creative briefs. | | creative_enhance_image | Analyze an image URL and return a creative, model-ready text prompt (enhanced_prompt). Use with **generate + an image-to-image model_ref to apply the look. | | check_status | Poll async jobs. Pass **request_id** and the same **model_ref** you used in generate. | | check_credits | Check your org's credit balance. | | upload_file | Prepare a file URL for use as generation input. | | recommend_model | Recommend models for a task (top pick + alternatives with model_ref). | | list_projects | List org studio projects available to your API key. | | list_project_media | List generation history for a project (project_id from list_projects). | | get_element_schema | Valid element categories and fields for a project kind (call before create_element). | | create_element | Create a studio element on an org project. | | search_documentation | Search curated Prologue docs — new-user guides (filmmaking / branding / character), studio workflows, credits, detection, MCP. | | get_project_snapshot | Structured JSON snapshot (scenes, shots, elements, text_summary). | | detect_elements | Detect elements in image/video/audio from a URL (charges org credits). | | detect_elements_script | Parse script text into scenes/shots/elements (dry_run defaults to true). |

Example workflow

Agent: recommend_model({ intent: "cinematic text to video, 16:9" })
→ top_pick.model_ref (prg_…), alternatives[], filter_summary

Agent: list_models({ category: "text-to-image" })
→ Each model: model_ref (prg_…), label, description, credits_estimate

Agent: list_projects({})
→ [{ id, name, kind, status, created_at }, …]

Agent: search_documentation({ query: "filmmaking storyboard workflow" })
→ Prefer when project.kind is filmmaking — hits NEW_USER_GUIDE-FILMMAKING_PROJECTS.md

Agent: list_project_media({ project_id: "<uuid>", page: 1, page_size: 20 })
→ { items: [{ id, url, type, prompt, … }], total }

Agent: get_project_snapshot({ project_id: "<uuid>" })
→ { project, summary, scenes, elements, text_summary }

Agent: get_element_schema({ project_id: "<uuid>", category: "character" })
→ { sections, fields, category_specific }

Agent: create_element({ project_id: "<uuid>", name: "Alice", category: "character" })
→ { element: { id, name, category, … } }

Agent: search_documentation({ query: "element detection credits" })
→ { results: [{ title, path, excerpt, relevance }] }

In-app Prologue Intent (Unified Playground, create-turn-v2) injects the matching new-user guide by project kind and exposes the same search via the `search_documentation` agent tool.

Agent: get_model_schema({ model_ref: "prg_…" })
→ JSON schema: prompt, aspect_ratio, num_images, etc.

Agent: generate({
  model_ref: "prg_…",
  input: { prompt: "a cat in a spacesuit", aspect_ratio: "16:9" }
})
→ Returns { images: [{ url: "https://..." }], creditsUsed: 10 }

For long-running jobs (video, 3D):

Agent: generate({ model_ref: "prg_…", input: { prompt: "..." } })
→ { status: "queued", request_id: "abc-123" }

Agent: check_status({ request_id: "abc-123", model_ref: "prg_…" })
→ { status: "completed", video: { url: "https://..." } }

Org API keys must use **model_ref** from GET /api/generate/models (with the same Bearer key). Raw provider paths are rejected for those requests.

Environment variables

| Variable | Required | Description | | ----------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- | | PROLOGUE_API_KEY | Yes | Your org API key (starts with sk-org-) | | PROLOGUE_BASE_URL | No | API base URL (defaults to https://prologue.ai) | | PROLOGUE_MCP_ICON_URL | No | URL shown as the MCP server logo in clients that support serverInfo.icons (defaults to https://prologue.ai/prologue-icon.svg) |

Logo / icon in Cursor

Cursor’s MCP list uses a letter placeholder for many custom servers. The Model Context Protocol allows the server to send optional **icons** during the connection handshake (initialize → serverInfo). This package now declares an icon pointing at your public Prologue mark (override with PROLOGUE_MCP_ICON_URL if needed).

Whether you see it depends on Cursor version and whether it renders serverInfo.icons for stdio servers. Official entries like Stripe/Supabase are often bundled in the app with their own artwork, which is why they always look polished. There is no separate icon field in mcp.json for arbitrary image uploads today—use the protocol icons URL (or a marketplace listing, if you publish there).

Credits

All generations deduct credits from your org wallet. Check your balance with check_credits and top up from the Prologue dashboard.

Production (prologue.ai) and Vercel Firewall

If MCP tools fail with 429 and HTML titled “Vercel Security Checkpoint”, the request never reached the app — Vercel’s edge bot protection blocked the MCP subprocess.

Fix (project owner, one-time in Vercel dashboard): add a Firewall custom rule to skip managed challenge for org API key traffic on MCP routes (/api/credits, /api/generate, /api/enhance-prompt, /api/creative-enhance-image, /api/schema, /api/mcp/*, /api/mcp/v1) when Authorization starts with Bearer sk-org-. See Model-gen/docs/STATUS_PAGE_SETUP.md.

Remote MCP (hosted)

Connect without running npx locally — same tools over Streamable HTTP:

| Setting | Value | |---------|--------| | URL | https://prologue.ai/api/mcp/v1 | | Auth | Authorization: Bearer sk-org-... on every request | | Local dev | http://localhost:3002/api/mcp/v1 |

Hosted MCP uses stateless JSON mode (one fresh transport per HTTP request), which fits Vercel serverless. Send Accept: application/json, text/event-stream on POST requests.

n8n / Zapier should use REST instead: docs/HTTP_API_REFERENCE.md.

Multi-client setup

Prologue MCP is one npm package (@prologue-ai/mcp) for stdio clients, plus hosted HTTP above. Copy-paste guides:

| Client / platform | Guide | |-------------------|-------| | Cursor | docs/clients/cursor.md | | Claude Desktop / Code | docs/clients/claude.md | | OpenClaw | docs/clients/openclaw.md | | Hermes Agent | docs/clients/hermes.md | | NemoClaw | docs/clients/nemoclaw.md | | OpenAI Agents | docs/clients/openai-agents.md | | LangChain | docs/clients/langchain.md | | Vercel AI SDK | docs/clients/vercel-ai-sdk.md | | CrewAI | docs/clients/crewai.md | | n8n (HTTP) | docs/clients/n8n-http.md | | Zapier (HTTP) | docs/clients/zapier-http.md | | REST reference | docs/HTTP_API_REFERENCE.md |

Optional installer (merges config without overwriting other servers):

node scripts/install-mcp-client.mjs --client cursor --api-key sk-org-...

The MCP server sends User-Agent: PrologueAI-MCP/1.0 and X-Prologue-Client: mcp on every request so you can scope that rule tightly.

With type: "balance" (the default), GET /api/credits returns total balance plus org fields: nonExpiringBalance, monthlyRemaining, monthlyAllocation, autoTopupEnabled, autoTopupPackCredits, autoTopupPoolCredits, gaugeMode (monthly | auto_topup), and autoTopupRemainingPercent (set when the UI would show “auto top-up remaining”).

Cursor plugin layout (this repo)

This package follows the Cursor plugin template layout so it can be submitted to the Cursor Marketplace:

| Path | Purpose | | ---------------------------- | ----------------------------------------------------------------------------------- | | .cursor-plugin/plugin.json | Plugin manifest (name, displayName, logo, mcpServers → mcp.json) | | mcp.json | Default MCP server definition (npx -y @prologue-ai/mcp@latest + env placeholders) | | assets/logo.svg | Marketplace / UI logo |

At the repository root (monorepo):

| Path | Purpose | | --------------------------------- | ------------------------------------------------------------------ | | .cursor-plugin/marketplace.json | Registers the plugin and points source at Model-gen/mcp-server |

Validate before submitting to Cursor:

# from repository root (Prologue-Gen2)
pnpm validate:cursor-plugin
# or: node scripts/validate-cursor-plugin.mjs

Submission: see Publish a Cursor Marketplace Plugin and the template README (email [email protected] or Slack per current Cursor docs).

Publish to npm

Prerequisites:

1. An npmjs.com account logged in locally (npm login).
2. The **@prologue-ai scope** must exist and your user must have publish rights (create the org on npm or adjust name in package.json if you use another scope).

From this directory:

pnpm install   # or npm install
npm run build
npm publish --access public

prepublishOnly runs npm run build automatically. After publish, npx -y @prologue-ai/mcp@latest matches the plugin mcp.json in this package.

Development

cd Model-gen/mcp-server
pnpm install
pnpm build

Why node dist/index.js prints nothing

The server speaks MCP over stdio (JSON-RPC on stdin/stdout). It is meant to be started by Cursor, Claude Desktop, or the MCP Inspector — not used as an interactive CLI.

To debug tools manually:

cd Model-gen/mcp-server
pnpm dlx @modelcontextprotocol/inspector node dist/index.js

Set PROLOGUE_API_KEY (and optionally PROLOGUE_BASE_URL) in the environment before starting the inspector, or configure them in the inspector UI if supported.

License

MIT