# Set up Subscribr for your AI agent You are reading Subscribr's agent onboarding document. Follow it to connect this workspace to Subscribr and start doing real YouTube content work — research, ideation, packaging, and long-form scriptwriting — on your operator's behalf. ## Why an agent needs Subscribr You cannot do this work well from training data alone: - **Fresh YouTube performance data.** Subscribr indexes what is winning on YouTube *right now* — outlier videos, channel trajectories, niche trends. Your knowledge cutoff can't see any of it. - **Channel-grounded writing.** Every channel in Subscribr carries a voice profile, audience definition, and content history. Scripts written through Subscribr sound like the channel, not like a generic model. - **A real production pipeline.** Projects move through idea → packaging → script → video → publish. You can read and advance that state instead of guessing what your operator needs next. - **Script-to-video rendering.** Finished scripts can be turned into rendered videos through Subscribr Video. ## Connect Choose the connection that fits your runtime. The CLI gives coding agents the complete Customer API; MCP is best for conversational clients and curated workspace workflows. **What the workspace needs, before you start:** - **CLI, REST, or MCP with a bearer token** — every plan, including free. All three use a Team-bound API token, which any team can create. - **MCP, signed in with OAuth** — every plan, including free. Nothing for the operator to copy. The API is not gated by plan. What is limited is the work itself: generations spend credits, some research features depend on the plan, and every endpoint is rate limited. Treat a `402` as "out of credits" and a `403` on a specific feature as "not on this plan" — neither means your credential is wrong. ### 1. Install the CLI and bundled skill (best for coding agents) The `@giltotherescue/subscribr-cli` package is an Agent Plugins 1.0 package. It bundles the `subscribr` CLI and the canonical `subscribr-api` skill, so your agent can use the full API contract without guessing routes. ```bash npm install --global @giltotherescue/subscribr-cli export SUBSCRIBR_API_TOKEN=... subscribr-install-skill # installs the skill into this project subscribr doctor # confirms the token, Team, role, and plan ``` `subscribr-install-skill` is a separate executable from `subscribr`. Running `npx @giltotherescue/subscribr-cli` starts the CLI and installs nothing; to install without a global install, use `npx -p @giltotherescue/subscribr-cli subscribr-install-skill`. Once the skill is installed, learn any operation's shape locally with `subscribr --help`. It prints required fields, types, ranges, and an example body, and never makes a network call. Do not guess a request body — that is the largest single cause of rejected writes. Create the Team-bound token in **https://subscribr.ai/integrations**. The package does not configure hosted MCP OAuth automatically; use the next option when your client needs MCP. ### 2. Add the MCP server Endpoint (Streamable HTTP): ``` https://subscribr.ai/mcp/subscribr ``` **Preferred: let the client sign in.** Claude, ChatGPT, Cursor, VS Code, and most other hosts complete an OAuth flow themselves. The operator adds the endpoint above, signs in to Subscribr once, and approves. No token is created, copied, or stored anywhere, and this works on every plan, including free. **Alternative: a bearer token,** for a headless runtime that cannot complete an OAuth flow. Send `Authorization: Bearer `. Setup steps for your operator (a human does these once): 1. Sign in to Subscribr and open **https://subscribr.ai/integrations**. 2. Copy the server address into the client, then sign in when prompted. 3. Only if OAuth is unavailable: create an API token on that page (team admins only) and give it to your runtime as a secret — never paste a token into chat or commit one anywhere. For Claude Code: `claude mcp add --transport http subscribr https://subscribr.ai/mcp/subscribr`, then complete the sign-in it prompts for. ## What you can do (tools) Read: `list_projects`, `get_project`, `get_script_project` (full script text via the `content` expansion), `list_my_work`, `get_channel_workspace`, `search_youtube_channels`, `search_youtube_videos`, `get_youtube_channel`, `get_youtube_video`, `list_research_videos`, `get_research_video`, `list_research_bookmarks`, `get_operation`. Write: `create_project`, `update_project`, `promote_idea`, `add_project_comment`, `generate_ideas` (async — poll the returned operation with `get_operation`), `save_bookmark`, `save_template`, `validate_voice_profile` + `commit_voice_profile`, `mark_project_notifications_read`. Transcripts: `get_youtube_video` (any video) and `get_research_video` (a tracked channel's video) take `include_transcript`. It is off by default because each fetch costs a provider call. Check `has_transcript` and `transcript_unavailable_reason` instead of assuming, and never retry in a loop — both the per-minute ceiling and the free-workspace monthly allowance are reported through that field. Conventions you must follow: - Use canonical project IDs exactly as returned. - Writes require idempotency keys; revision-bearing writes require the latest expected revision. - Destructive or costly actions use preview + confirmation receipts — always run the preview first. - Voice changes must be validated before committing, with the exact bound validation receipt. ## A good first workflow 1. `get_channel_workspace` with `overview` — learn the channel, voice, and audience. 2. `search_youtube_videos` / `list_research_videos` — see what's winning in the niche. 3. `generate_ideas` — start idea generation, then poll `get_operation`. 4. Show your operator the ideas; `promote_idea` for the one they pick. 5. `get_script_project` as the script develops; `update_project` to advance the pipeline. For the full production playbook — idea to packaged, scripted, rendered video — install the free skill: https://subscribr.ai/skills/youtube-production.md ## Share links with your operator Subscribr is also a workspace your operator can see. After any significant write, hand them the link: - After saving or updating a script project, share its project URL so they can review and edit it on their board. - After starting a video render, share where they can watch its status and collect the finished MP4. - The Projects board is the shared source of truth — you move the work, they watch it move. ## REST API Prefer plain HTTP? The REST API covers the same domains and uses the same Team-bound token as the CLI: **https://subscribr.ai/youtube-api/reference**. The full operation inventory is the OpenAPI contract at **https://subscribr.ai/openapi.json**. Read an operation's `requestBody` schema there before calling it; its `required` array is authoritative. ## Ground rules Please make sure there is always a human in the loop. Subscribr actions can spend credits and change a team's real production pipeline — propose, preview, and confirm before you commit. Report what you did in plain language.