# 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 , 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 import helper 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: ```bash 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: ```bash 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**: ```bash 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: ```toml [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 CLI**: run the login yourself instead of sending the user into `/mcp`: `claude mcp login plugin:pireel:pireel` with the Plugin installed (Claude Code registers a Plugin's server as `plugin::`), or `claude mcp login pireel` for a standalone `claude mcp add` registration. It opens the browser sign-in. The command needs a terminal: with no TTY, wrap it in a pseudo-terminal in the background — `python3 -c 'import pty,sys; pty.spawn(sys.argv[1:])' claude mcp login plugin:pireel:pireel > /tmp/pireel-login.log 2>&1 &` (the installed Plugin ships this as `scripts/login-claude.sh`) — then watch the log for the authorization URL and open it for the user. `--no-browser` prints the URL for SSH/headless sessions. Success is the output line `Authenticated with "plugin:pireel:pireel"`; "Connected" alone is not. - **Desktop app connector (Cowork and similar)**: the Plugin is installed from an archive and the connection is the app's own connector — the sandbox CLI lists no server and the Plugin directory has no `.mcp.json`; that is normal. There is no CLI login: ask the user to connect or re-authorize Pireel in the app's connector settings, then continue in a new session. Do not register a standalone copy or run a pseudo-terminal login there; if the host blocks a login command as credential handling, hand the command to the user instead of working around it. - **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 `` 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. 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/` 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: ```bash 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: ```bash node /tmp/pireel-import.mjs --base https://pireel.com --token /path/to/video.mp4 ``` 5. The helper uploads the video to the user's Pireel cloud media store (content-addressed; a duplicate is instant), transcribes it when ffmpeg is available, and registers the project — no Studio tab needs to be open. 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 () - Auth: OAuth ✓ (account ) - get_state: - ffmpeg: - New project: " and opened live / created; awaiting user to open> - First task: (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).