Pireel

Copy the following and send it to your agent.

Your agent will choose between the Plugin, Skill and MCP automatically.

Read pireel.com/connect-agent.md, connect Pireel, and start a new video editing project.

The agent will open Pireel and create a new editing project.

Pireel Studio — agent connection guide

Pireel Studio (https://pireel.com) is a multi-source, multi-output AI video editor with a multi-track timeline. This is the production-environment connection guide. Every endpoint and server name below is fixed to production.

Give this to your agent

You do not need to choose an installation format. Send this document to the agent you already use and describe the outcome:

English: Read <this document's URL>, connect Pireel, and start a new video editing project. Prefer the Plugin; use the Skill only when Plugins are unsupported.

中文：请阅读 <本文档 URL>，连接 Pireel 并启动一个新的剪辑项目。优先使用 Plugin，不支持 Plugin 时再使用 Skill。

The agent should inspect the capabilities available in its current environment, follow the priority below, and ask you only for approvals or account actions it cannot complete itself.

If you are an agent reading this for a user

This whole guide is your execution contract. Read it fully before taking setup actions. Choose by supported capability, not by vendor name. Complete the connection, create the requested project, and continue to the first useful editing step; do not stop after installing or authenticating.

Sandbox rule: your shell sandbox may block ALL network (even localhost). Run network commands (connectivity probes, the import helper) OUT of sandbox — request approval instead of attempting a sandboxed run first. NEVER conclude the Pireel server is down from a sandboxed curl: if the user says it is running, trust them — your MCP connection and codex mcp login do not go through the shell sandbox and will work regardless.

Environment contract: this entry connects only to Pireel production. Use the pireel MCP server at https://pireel.com/api/studio/mcp. Do not infer or select an environment from the tools already installed in the host.

Installation priority

Choose the first route the current host can actually support:

  1. Matching Pireel Plugin already available: use it now only when its bundled pireel MCP server targets https://pireel.com/api/studio/mcp.
  2. Plugin supported: install the Pireel Plugin through the host's native Plugin manager. If only a standalone Skill or manually registered MCP is present, migrate it through the verified sequence below instead of treating it as the preferred route. “Plugin” here includes a host-native app/package that bundles both workflow and MCP. Plugin takes priority over Skill.
  3. Plugin unsupported, matching standalone Skill/MCP already available: use that production connection and keep its workflow updated.
  4. Plugin unsupported, Skill supported: install the standalone Pireel Skill, read its getting-started reference in the same turn, and register the remote Pireel MCP server.
  5. Neither Plugin nor Skill supported, MCP supported: register the remote MCP server and use this document as the workflow contract.
  6. No compatible installation authority: tell the user the single UI action or administrator approval required. Do not dump unrelated shell commands on them.

Do not ask the user to choose between Plugin, Skill, and MCP. Apply this priority yourself. Product names and client branding are not evidence of capability; inspect the tools, installation APIs, shell, filesystem, and MCP settings exposed in this session.

An installed tool counts as available only when it matches that fixed server name and endpoint. Otherwise continue down the installation priority and install the production connection. Do not inspect another Pireel environment and decide to substitute it.

Web/mobile/remote surfaces can edit cloud projects, use stock media, and call server-side tools after a connection exists. Local-file paths and the loopback importer require an agent running on the user's computer. If local access is unavailable, keep setup moving with a new cloud project and ask the user to upload media in Studio when it is needed.

Step 1 — Connect Pireel using the highest-priority supported route

MCP endpoint: https://pireel.com/api/studio/mcp (streamable HTTP, stateless).

Plugin — preferred

If the production pireel tools for https://pireel.com/api/studio/mcp are already present from the Plugin, skip installation and continue to Step 2. Otherwise, when the host supports Plugins, install Pireel Studio with its native Plugin installer. An existing standalone Skill or manual MCP entry does not skip this migration. The Plugin bundles the workflow and authenticated MCP connection; do not add another standalone copy.

For an existing standalone installation, migrate safely: install the Plugin first, reload/start a new session when required, authenticate, and verify get_state through the Plugin's production endpoint. Only after verification succeeds may the agent disable/remove the standalone Skill and manual pireel MCP entry through the host's normal approved flow. Never delete the working connection before the Plugin is proven. If cleanup is not directly available, leave the old copy dormant and ask for the single required UI/admin action.

If the host exposes this repository-marketplace CLI, the agent may use:

codex plugin marketplace add https://github.com/pireel/pireel-agent
codex plugin add pireel@pireel-marketplace
codex mcp login pireel

If the host labels native integrations as “apps” instead of “Plugins”, treat an app that bundles the Pireel workflow and MCP connection as the Plugin route. In a web or managed workspace, use the available Plugin/app UI; never invent a local shell command.

Standalone Skill — fallback

Use this only when Plugin installation is unsupported and the current host supports Agent Skills. Install through the host's normal command-approval flow:

npx skills add pireel/pireel-agent

Read the installed core pireel Skill and getting-started reference immediately in this turn. Do not end at “installed” or require a new conversation before continuing.

MCP-only — final fallback

Use this only when neither Plugin nor Skill installation is supported.

Claude Code:

claude mcp add --transport http pireel https://pireel.com/api/studio/mcp

Codex: add to ~/.codex/config.toml (create the block if absent). The oauth_resource line is REQUIRED — without it Codex does not attempt OAuth and expects a static bearer token:

[mcp_servers.pireel]
url = "https://pireel.com/api/studio/mcp"
oauth_resource = "https://pireel.com/api/studio/mcp"

(Codex field names vary slightly across versions — if this shape is rejected, check codex mcp add --help for the current remote-HTTP syntax.)

Other MCP clients: use the client's native remote-MCP configuration and register the endpoint above. OAuth discovery is standard (RFC 8414 / 9728 metadata at https://pireel.com/.well-known/oauth-authorization-server and https://pireel.com/.well-known/oauth-protected-resource).

Step 2 — Authenticate (OAuth)

The endpoint answers unauthenticated calls with a WWW-Authenticate challenge; your MCP client discovers the OAuth flow from it automatically.

  • Codex: run codex mcp login pireel — it opens the browser sign-in; the user logs into their Pireel account and approves.
  • Claude Code: the client prompts for authentication on first use (or via /mcp) — follow the browser flow.
  • Managed Plugin/app surfaces: use the authorization action shown by the integration. If an administrator must approve the connection, ask for that one action and resume after approval.

Step 3 — Verify the connection

Call the get_state tool. Interpret the result:

  • A <composition_state> snapshot → the user's studio tab is open and bridged; fully connected.
  • A snapshot prefixed OFFLINE MODE → connected; no tab open, but data-level editing works directly against the user's latest cloud project.
  • no cloud project → connected; the account is fresh. Move to Step 4.
  • HTTP 401 after OAuth → re-run the login flow; the token may not have been granted.

Step 4 — Create and open the new editing project

The user prompt at the top explicitly asks for a new project. Call create_project now; do not silently reuse the latest project. Give it a concise working title based on the user's stated goal, or use a neutral title when no goal is known.

Next, call create_browser_handoff with that project_id and open the returned url with your own built-in/embedded browser tool — the browser whose pages you can see and control. On Codex, use the in-app Browser runtime. Never open it via the OS open/start/xdg-open command, the user's default browser, or an already-connected external Chrome proactively: the ticket is single-use, so spending it on a surface you cannot see wastes it and leaves you blind. Keep the tab visible and open past your turn. If a local-helper attempt explicitly returns local loopback is unreachable from this browser, release the isolated tab, mint one fresh handoff, open it in a controllable connected browser that shares the host loopback, and retry once with a fresh token. The handoff URL expires in about 60 seconds; open it immediately and never print it in chat or share it as a link. To give the user a reusable link, provide https://pireel.com/zh/studio/<projectId> instead. If the host has no embedded browser, ask the user to open that plain project URL.

Step 5 — Bring in media and begin the matching workflow

Ask for the editing goal and media source only if the user has not supplied them already. Identify the closest scenario Skill (pireel-talking-head-edit, pireel-long-to-shorts, pireel-montage-edit, pireel-batch-remix, pireel-commerce-video, or pireel-product-demo) and read it with the core pireel Skill when those Skills are available.

A. Local video on a local agent — keep the Studio tab open first:

  1. Call import_media with no arguments to obtain a short-lived import token. Never pass an OAuth token to the shell.
  2. Use the helper bundled with the Plugin/Skill, or fetch the public helper when it is unavailable: 
    curl -fsSL https://pireel.com/import-media.mjs -o /tmp/pireel-import.mjs
  3. Ensure ffmpeg/ffprobe are available. If installation is denied, continue with a degraded import and disclose that transcription or metadata may be deferred.
  4. Run the helper with Node 20 or newer: 
    node /tmp/pireel-import.mjs --base https://pireel.com --token <token> /path/to/video.mp4
  5. The main video streams over loopback directly into the open Studio tab and stays on the user's device; only the small extracted audio needed for transcription is uploaded. Then call get_state and begin the selected workflow.

B. Web/mobile/remote agent: continue with the new cloud project. Use stock or generated media when requested, or ask the user to upload their local files into the open Studio project. Do not claim a remote agent can read a path on the user's device.

C. Browser-first user: if the user prefers to control the browser upload, keep the project open and wait for the upload; the live bridge connects automatically. Then inspect get_state and begin editing.

Self-report (print this when done)

Pireel setup complete:
- MCP server: registered (<client name>)
- Auth: OAuth ✓ (account <email if known>)
- get_state: <connected live / offline mode / fresh account>
- ffmpeg: <available / installed now / degraded>
- New project: <created project "<title>" and opened live / created; awaiting user to open>
- First task: <imported <file> (N transcript sentences) / using cloud media / awaiting media or brief>

Troubleshooting

  • connection refused from your shell but the user says the server is running: your command sandbox has no network. Re-run the command out of sandbox (with approval). Do not report the server as down.
  • 401 loop after OAuth: the browser session used for approval must be logged into the SAME Pireel account; retry login, then get_state.
  • studio_not_open on a tool: only video-dependent operations need the tab (read_script when transcription is missing, analyze_visual, capture_frame, export, Pireel-hosted generation). Data-level tools—including read_script when a transcript is already stored—fall back to offline mode automatically. Ask the user to open their project at https://pireel.com for the video-dependent ones.
  • Helper fails with fetch failed/TLS/proxy errors: retry through the user's local HTTP(S) proxy if one is running (set HTTPS_PROXY/HTTP_PROXY, e.g. http://127.0.0.1:7890); unset after testing.
  • Node < 20 (openAsBlob is not a function): use a newer Node runtime for the helper.
  • file_too_large: single file limit is 2 GB — with the user's consent, trim/transcode locally with ffmpeg first, or upload via browser.

Billing note

Agent orchestration and all BYO text/HTML generation burn the user's own agent subscription, not Pireel credits. Pireel bills only media generation (images/video) and the audio/vision pipelines (transcription, visual analysis).