Build a UGC Ad Pipeline with Claude Code: An Engineer's MCP Guide

Claude Desktop's MCP integration is great for one-off ad generation. Claude Code's MCP integration is for everything else — automated batches, skill-based workflows, multi-MCP orchestration, CI runs that produce ad variants overnight. This is the developer's playbook: how to wire @ugccopilot/mcp into a Claude Code project, structure agents that don't burn credits on dumb mistakes, and ship a pipeline that turns a Notion brief into 10 finished ad variants without a human in the loop.

Why Claude Code (vs Claude Desktop, vs the raw API)

Three legitimate ways to call UGC Copilot from Claude. Choose based on the workflow:

Tool	Best for	Friction
Claude Desktop + MCP	One-off ads, brainstorming sessions, free-tier exploration	Zero — paste config, restart, done
Claude Code + MCP	Repeatable workflows, multi-step agents, codebase-aware tasks, CI runs	Low — config file in repo, optional skills directory
Direct REST API	Headless production systems, customer-facing automations, paid agent products	High — write your own retry/idempotency/webhook handling

Claude Code is the right tool when an agent should remember a workflow across sessions, run unattended, or coordinate multiple MCPs at once. If you've already read our direct API integration guide, this is the version with less plumbing — Claude Code handles the orchestration loop, you bring the prompts and skills.

Setup — adding the MCP server to a Claude Code project

Claude Code reads MCP server definitions from .mcp.json at the project root, with optional inheritance from a user-level config at ~/.claude.json. For project-scoped use:

// .mcp.json
{
  "mcpServers": {
    "ugc-copilot": {
      "command": "npx",
      "args": ["-y", "@ugccopilot/mcp@latest"],
      "env": {
        "UGC_COPILOT_API_KEY": "ugc_live_..."
      }
    }
  }
}

Don't commit the API key. Use ${UGC_COPILOT_API_KEY} in .mcp.json and source the env var from a .envrc or shell profile. Treat the key like any other production secret.

Verify the server loaded: open a Claude Code session in the project and run /mcp. The server's twelve tools should appear in the list. If they don't, run claude --debug and check the MCP startup logs for the error.

The first agent task

The minimum viable workflow: take a product brief and produce three finished ad variants.

I have a product: a $34 ceramic pour-over coffee dripper for home
brewers, 28-42. Read the brief in product-brief.md, then use the
ugc-copilot tools to:

1. Generate three different scripts using contrasting hook formulas
   (curiosity-gap, unpopular-opinion, and POV-realism).
2. Generate one scene image per script.
3. Render each as a Sora 2 std video.
4. Apply a price-overlay caption to each rendered video.
5. Save the final URLs to ads/output.md with a one-line summary
   per variant.

Quality gate: if any script feels generic or any render fails, retry
once before saving. Total budget: 80 credits.

Claude Code executes this task in roughly 4–7 minutes. The credit math:

• 3× generate_script = 3 credits
• 3× generate_image std = 3 credits
• 3× render_video Sora 2 std = 54 credits
• 3× apply_text_overlay = 3 credits

Total: 63 credits ≈ $4.41–$7.88 at subscriber add-on rates ($0.07–$0.125 per credit). Comfortably under the 80-credit budget. The "retry once" gate adds at most 30 credits if every variant needs to retry, which almost never happens in practice.

The skill file pattern

Drop the same task in .claude/skills/generate-ad-variants.md and the one-off prompt becomes a reusable skill:

// .claude/skills/generate-ad-variants.md
---
description: Generate N ad variants for a product brief using contrasting hooks
arguments: [count, briefPath]
---

Read the product brief at $briefPath. Then use the ugc-copilot MCP
tools to:

1. Generate $count scripts, each with a different hook formula from
   this list: curiosity-gap, unpopular-opinion, POV-realism,
   pain-point, social-proof.
2. Generate scene images for each script (std quality unless the
   user requests hq).
3. Render each via render_video. Default to Sora 2 std unless the
   brief mentions cinematic/long-form (Veo) or trend-cloning (Kling).
4. Apply price-overlay captions if the brief includes a price.
5. Save final URLs to ads/output.md with format: variant-N | hook-type
   | engine | URL | one-sentence summary.

Always set a credit budget at 30 × $count. Halt and ask if budget
exceeded. If a render fails, retry once with the same engine before
falling back to Seedance 2.0 std.

Now invoking the skill with 5 and product-brief.md runs the entire pipeline with sensible defaults. The arguments frontmatter declares positional inputs, and $count / $briefPath substitute at invocation. Skills are how agent prompts become infrastructure.

Multi-MCP orchestration

The point of Claude Code's MCP integration is that servers compose. A real-world ad pipeline uses 3–5 MCPs together. Common pattern:

• ugc-copilot — script, image, render, overlay (covered above)
• filesystem — read briefs, write output manifests
• github — open a PR with the rendered output URLs for review
• slack — post progress updates to the team channel

The agent task changes from "generate three ads" to:

Read the latest brief in /briefs (filesystem MCP). Generate 5
variants using the generate-ad-variants skill. Open a PR against
the campaign repo with the output manifest (github MCP). Post a
summary in #marketing-experiments with the PR link (slack MCP).

Same agent, four MCPs cooperating. The user wrote 4 sentences. The agent did 30 tool calls. That's the agentic-stack point.

Real benchmarks from a tested run

Numbers from an actual production run (May 2026, Claude Sonnet 4.6, project context warm):

Metric	5-variant batch	15-variant batch
Wall-clock time	5m 40s	14m 12s
Agent thinking time	~30s	~75s
Render time (parallel-bound)	~5m 10s	~13m
Credits consumed	108	312
Cost (200-cr pack)	$13.50	$39
Cost (10k-cr pack)	$7.56	$21.84
Final ad count	5/5	14/15
Retries triggered	0	1 (one Sora 2 render hung)

The 14/15 outcome on the larger batch is normal — at scale, expect 5–10% of renders to need a retry. The skill's "retry once before falling back" rule produces a usable variant on the second attempt about 80% of the time.

Engine routing in the skill

Without explicit guidance, Claude Code defaults to Sora 2 std for most renders. That's a reasonable default, but it's not optimal for every workflow. A more deliberate engine-routing rule in the skill produces measurably better outputs:

Engine selection rules for this skill:
- Hero/cinematic content (15s+, brand-led): Veo 3.1 std
- Lip-sync/dialogue scenes: Sora 2 std
- Image-to-video from a fixed reference: Kling 3.0 std
- Cost-optimized batch testing (8+ variants): Seedance 2.0 std
- Hook-test pre-render phase: Seedance 2.0 std with quality gate
  before promoting winners to Sora or Veo.

This kind of explicit routing in the skill is the difference between an agent that produces output and one that produces good output. For deeper engine-selection logic with cost benchmarks, see the Sora 2 vs Veo 3.1 comparison and Seedance 2.0 guide.

Failure modes you'll actually hit

Three patterns we've seen across hundreds of agent runs:

Tool-call drift

Even with a structured skill, agents occasionally pass an invalid engine value or skip a required argument. The MCP server validates and returns a structured error; Claude Code typically self-corrects on the second try. If you see persistent drift on a specific tool, tighten the skill's wording — replace "use the right engine" with "engine MUST be one of: sora, veo, kling, seedance" and the success rate jumps.

Concurrency exhaustion

Tier concurrency caps (3/8/25 in-flight slots for Creator/Pro/Business) apply per API key. If a skill submits 20 renders in parallel on a Pro key, the 9th onward returns a 429. Two options: lower the parallelism in the skill ("submit at most 6 renders simultaneously"), or upgrade the tier. The skill author who burns the most credits debugging this is usually the one who didn't realize the batch was queueing serially because of repeated 429s.

Cache-stale MCP server version

Claude Code spawns the MCP server via npx, which caches resolved packages in ~/.npm/_npx/. After a new MCP version ships, the next session may still be running the old one. Fix:

rm -rf ~/.npm/_npx
# Then exit and restart Claude Code.

Pinning @latest in .mcp.json makes npx more aggressive about re-checking on cold start. For production stability, lock to a specific version (@ugccopilot/mcp@0.1.1) and bump deliberately.

From prototype to production

A skill running in a developer's Claude Code session is a prototype. The same skill running on a schedule, against the team's brief queue, with output reviewed by humans before going live — that's production. The transition path:

1. Skill matures. The skill file in .claude/skills/ stops changing week-over-week. Tweaking stops; only the inputs vary.
2. Output review process exists. Generated ads land in a manifest (or a draft branch) that someone has to approve before publication. Humans don't need to be in the loop on generation — but they should be on launch.
3. Schedule the run. A cron-style scheduler (Claude Code in CI, or a dedicated agent runtime) executes the skill on the brief queue daily or per-trigger.
4. Monitor credit spend. Each run logs credits consumed. Anomalies (3× normal spend) get flagged. Track per-ad cost over time as a unit-economics input.
5. Promote to direct API. Claude Code is an interactive CLI; for scheduled or unattended runs, migrate the skill's logic to a direct API client running in your CI system or a small agent runtime. The MCP version stays around as the team's interactive interface; production runs hit REST directly. The migration path is in the direct API integration guide.

Composition with other agentic patterns

Claude Code's MCP integration composes with most agent patterns we've documented:

• The product-URL-to-ad-variants pipeline can run as a Claude Code skill against a Shopify export.
• The 500-ads-per-month agent pattern is a Claude Code project running on schedule with a budget gate.
• The paid-agent-as-a-product playbook starts as a Claude Code skill before graduating to a hosted runtime.

The pattern: prototype interactively in Claude Code with MCP, validate the workflow, then decide whether to keep it MCP-based or migrate to a more headless architecture.

Conclusion

The Claude Code + UGC Copilot MCP combination is the lowest-friction way to ship an automated ad pipeline. Skill files, multi-MCP composition, and a deliberate engine-routing rule cover 80% of what a custom-built agent would do, at 20% of the engineering cost. Start with a single skill that produces 3–5 variants. Once the workflow stabilizes, add scheduling, monitoring, and human review. The migration to direct API is always available later — but most teams never end up needing it.