# UseMo — Agent, MCP & API Integration Reference

> Canonical capability and integration contract for coding agents, LLM tool routers, MCP clients, and backend developers.
> Updated: 2026-11-15
> Web guide: https://usemo.com/agents
> Markdown mirror: https://usemo.com/agents.md
> Public plugin & skills repo: https://github.com/gaufire/usemo-mcp
> Agent index: https://usemo.com/llms.txt
> MCP Server Card (unauthenticated tool catalog): https://api.usemo.com/.well-known/mcp/server-card.json
> OpenAPI 3.1: https://api.usemo.com/api/openapi.json

---

## 1. What UseMo completes (and when to choose MCP, CLI/SDK, or REST)

UseMo produces brand-grounded creative assets in a multi-tenant workspace: talking-head and presenter videos, digital-twin lip-sync clips, marketing images, professional headshots, consented face swaps (video, photo, meme, GIF), multi-format ad bundles, social graphics, SEO articles, and `.pptx` presentation decks. UseMo orchestrates open-source and third-party base models (such as FLUX, SDXL, Wan, Seedance, and Seedream) behind brand context, claim checking, and quality gates.

| Integration surface | Best for | Entrypoint / package |
|---|---|---|
| **Hosted MCP (`streamable-http`)** | Interactive AI assistants & IDEs (Cursor, Claude custom connector, ChatGPT Apps) | `https://api.usemo.com/mcp` (OAuth 2.1 + PKCE, or `X-API-Key: usm_...`) |
| **Local stdio MCP (`usemo-mcp`)** | Local coding agents (Claude Code, Codex, Cursor, Windsurf) using env/profile keys | `npx --yes --package @usemo.com/sdk@0.1.0 usemo-mcp` (Node.js `>=20`) |
| **CLI (`usemo`)** | Shell automation, CI pipelines, `--dry-run` validation, atomic asset downloads | `npm install -g @usemo.com/sdk@0.1.0` (`usemo --help`, JSON stdout) |
| **JS/TS SDK (`@usemo.com/sdk`)** | Node.js `>=20` services with schema validation, auto-idempotency, and bounded `wait` | `import { UseMoClient, downloadAsset } from '@usemo.com/sdk'` |
| **REST API + Webhooks** | Python, Go, Ruby, or high-volume webhook-driven backends | `https://api.usemo.com/api/v1` + `POST /api/v1/webhooks` |
| **ChatGPT Custom GPT Action** | No-code Custom GPTs | `https://api.usemo.com/api/integrations/chatgpt/openapi.json` |

---

## 2. Quick setup by client

### One-line CLI setup across coding agents
```bash
# Claude Code (Streamable HTTP + OAuth)
claude mcp add --transport http usemo https://api.usemo.com/mcp

# OpenAI Codex CLI
codex mcp add usemo --url https://api.usemo.com/mcp

# Gemini CLI extension
gemini extensions install https://github.com/gaufire/usemo-mcp

# Grok Build
grok mcp add --transport http usemo https://api.usemo.com/mcp

# Install composable SKILL.md pack (Cursor / Claude Code / Codex)
npx skills add gaufire/usemo-mcp
```

### Hosted MCP (`https://api.usemo.com/mcp` — Cursor, VS Code, Claude, ChatGPT)
- **Cursor one-click:** `https://cursor.com/link/mcp/install?name=usemo&config=eyJ1cmwiOiJodHRwczovL2FwaS51c2Vtby5jb20vbWNwIn0%3D`
- **VS Code (`.vscode/mcp.json`):** `{"servers": {"usemo": {"type": "http", "url": "https://api.usemo.com/mcp"}}}`
- **Cursor / Claude Desktop (`mcp.json`):**
```json
{
  "mcpServers": {
    "usemo": {
      "url": "https://api.usemo.com/mcp"
    }
  }
}
```
Complete UseMo OAuth 2.1 sign-in when prompted, or pass `X-API-Key: usm_...` in clients that use static headers.

### Local stdio MCP (`@usemo.com/sdk`, Node.js >= 20)
```json
{
  "mcpServers": {
    "usemo": {
      "command": "npx",
      "args": ["--yes", "--package", "@usemo.com/sdk@0.1.0", "usemo-mcp"],
      "env": {
        "USEMO_PROFILE": "work"
      }
    }
  }
}
```
Save a local profile once without putting secrets in shell history (`printf '%s\n' "$USEMO_API_KEY" | usemo login --key-stdin --profile work`), or inject `USEMO_API_KEY` from your client's secret store. Never commit real `usm_...` keys to repository config files.

---

## 3. Authentication, identity & base URLs

Send a workspace-scoped API key (created in `https://app.usemo.com/settings` under **Settings -> API Keys**) in either header (`X-API-Key` is canonical):

```http
X-API-Key: usm_<your_workspace_key>
Authorization: Bearer usm_<your_workspace_key>
```

- Sending two different API keys on the same request is rejected with `401`.
- Never embed `usm_...` API keys in browser bundles; call UseMo from a backend or an authenticated MCP client.
- Verify the active workspace, plan, scopes, remaining credits, and concurrency limits before paid work:
  - MCP: `usemo_whoami` and `usemo_get_capabilities`
  - CLI: `usemo whoami --json` and `usemo capabilities --json`
  - REST: `GET /api/v1/whoami` and `GET /api/v1/capabilities/generation`

| Environment | Base URL |
|---|---|
| Production REST | `https://api.usemo.com/api/v1` |
| Production MCP | `https://api.usemo.com/mcp` |
| Staging REST | `https://api-staging.usemo.com/api/v1` |

---

## 4. Idempotency, asynchronous jobs, outputs & webhooks

### Idempotency (`X-Idempotency-Key`)
Paid generation endpoints accept `X-Idempotency-Key: <unique-key>` (1–200 chars, e.g. UUIDv4 per logical step). Reusing the same key **and payload** within 24 hours returns the original job response without re-running or double-charging.

### Job lifecycle & recovery
Creation endpoints enqueue work and return a job receipt (`status`: `queued` | `processing` | `completed` | `failed` | `cancelled`):

```json
{
  "job_id": "2f9e5d10-7c8d-4a51-9b0f-1c2d3e4f5a6b",
  "status": "queued",
  "queue_name": "image|video|compose",
  "estimated_time_sec": 12,
  "credits_cost": "1.00"
}
```

- **Poll**: `GET /api/v1/jobs/{job_id}` (MCP: `usemo_wait_for_job` or `usemo_job_status`). When `status == "completed"`, read `result_urls` and `result_assets`.
- **Timeouts do not cancel jobs**: if a bounded wait times out while `status` is `queued` or `processing`, resume polling `job_id`. Never submit a duplicate render blindly.
- **Cancel & refund**: `POST /api/v1/jobs/{job_id}/cancel` (MCP: `usemo_cancel_job`) aborts a `queued` or `processing` job and refunds held workspace credits.
- **Signed URL expiry**: CDN URLs in `result_urls` can expire. Persist the `asset_id` and call `GET /api/v1/assets/{asset_id}` (MCP: `usemo_get_asset`) to mint a fresh download URL without regenerating. Never send `X-API-Key` to the CDN host when downloading media.

### Webhooks (`POST /api/v1/webhooks`)
```json
{
  "name": "production-worker",
  "target_url": "https://example.com/webhooks/usemo",
  "events": ["job.completed", "asset.created"]
}
```
Every webhook request carries `X-UseMo-Signature` (HMAC-SHA256 over raw body). Verify signatures in constant time and deduplicate by `job_id` / `asset_id` (up to 5 exponential-backoff retries on non-2xx responses).

---

## 5. Capability reference (`/api/v1`)

### VIDEOS

#### `POST /video/create` — Brief to grounded, quality-gated video (recommended)
Plans a brand-grounded storyboard (blocks ungrounded claims before GPU spend), then renders with identity and realism gates.
```json
{
  "ask": "30-second pitch for our B2B SaaS product",
  "twin_id": "uuid",
  "brand_voice": "concise, operator-to-operator",
  "async_plan": true
}
```
Returns `{shippable, storyboard, job}`. If `shippable` is `false`, no render credits were spent.

#### `POST /video/storyboard` & `POST /video/scene-video/quote` — Read-only plan & tier quote
Draft a storyboard (`{"ask": "..."}`) and estimate `draft` / `standard` / `premium` prices (`{"storyboard": {...}, "tier": "standard"}`) before spending credits.

#### `POST /video/talking-head` & `POST /video/talking-head/quote` — Scripted multi-shot talking head
1–6 script lines with identity and lip-sync gating (`{"face_image_url": "https://...", "lines": ["..."], "voice_id": "onyx", "aspect_ratio": "16:9"}`). Quote first via `POST /video/talking-head/quote`.

#### `POST /video/script-to-video` — Script to narrated or twin-presented video
```json
{
  "script": "Full spoken script at least twenty characters long...",
  "aspect_ratio": "9:16",
  "twin_id": "uuid"
}
```

#### `POST /video/generate` — Image-to-video animation
Requires `input_image` (`source_url` or `asset_id`) and `duration_sec` in `[5, 15, 30, 60]`.
```json
{
  "input_image": {"source_url": "https://example.com/frame.png"},
  "motion_prompt": "slow dolly-in, subtle natural head nod",
  "duration_sec": 5,
  "resolution": "720p",
  "quality": "quality"
}
```

#### `POST /video/face-swap` & `POST /video/gif-face-swap` — Consented video/GIF face swap
Adult non-NSFW media only; requires `consent_confirmed: true` (or an enrolled `twin_id` with verified consent). Plan face limits on `/video/face-swap`: free=0, starter=1, pro=3, business=5, enterprise=32.
```json
{
  "gif_url": "https://example.com/reaction.gif",
  "source_face_url": "https://example.com/adult-face.jpg",
  "consent_confirmed": true
}
```

#### `POST /video/stitch` — Concatenate clips (`{"clips": [{"asset_id": "uuid"}, {"asset_id": "uuid"}]}`)

---

### IMAGES & EDITS

#### `POST /generate` — Text-to-image
Models: `flux-dev` (default), `sdxl`, `flux2_flex`, `flux2_pro`. Note: `AssetInput` fields (`face_reference`) take `source_url` or `asset_id`.
```json
{
  "prompt": "clean studio product photograph of a ceramic mug on warm oak",
  "model": "flux-dev",
  "num_images": 1,
  "aspect_ratio": "1:1",
  "face_reference": {"source_url": "https://example.com/reference-face.jpg"},
  "twin_id": "uuid"
}
```

#### `POST /image/profile-pic` — Identity-locked professional headshot
```json
{
  "photo_url": "https://example.com/selfie.jpg",
  "style": "corporate",
  "background": "modern sunlit office",
  "brand_id": "uuid"
}
```

#### `POST /edit/face-swap` & `POST /image/meme-face-swap` — Consented image/meme face swap
```json
{
  "source_face_url": "https://example.com/adult-face.jpg",
  "meme_template_url": "https://example.com/meme-template.jpg",
  "meme_name": "Drake Pointing",
  "consent_confirmed": true
}
```

#### `POST /enhance/upscale` — Image upscale (`{"image": {"source_url": "https://..."}, "scale": 4}`)

---

### ADS, SOCIAL, ARTICLES & DECKS

- `POST /collateral/ads-campaign` — Dispatches parallel ad jobs across `instagram_square` (`1:1`), `stories` (`9:16`), `youtube` (`16:9`), and `linkedin` (`1:1`) with claim checking. Returns `{"jobs": {"instagram_square": {...}, ...}}`.
- `POST /collateral/social-post` — Branded social graphic (`{"headline": "Launch day", "subtext": "...", "cta": "Try free", "aspect_ratio": "1:1"}`).
- `POST /collateral/deck` — Slide presentation `.pptx` (`{"title": "Q3 Business Review", "brief": "Overview, metrics, and next steps", "slide_count": 6}`).
- `POST /content/seo-article` — Brand-grounded SEO article (`{"topic": "How ops teams automate onboarding", "word_count": 1200}`).
- `POST /generate/text` — Written copy (`general`, `blog`, `email`, `deck`).

---

### DIGITAL TWINS, BRAND CONTEXT & LIBRARY

- `GET /twins` (`GET /digital-twins`) — List workspace twins/clones.
- `POST /twins/{twin_id}/voice/synthesize` — Generate spoken audio in a twin's consented voice.
- `POST /twins/{twin_id}/avatar/render` — Lip-sync a twin to `audio_asset_id`.
- `GET /context/profile` & `POST /context/sources/website` — Read or learn workspace brand context from a URL.
- `GET /assets`, `GET /assets/{asset_id}`, `GET /assets/search?q=...`, `GET /assets/{id}/similar` — Browse, refresh signed URLs, or semantically search workspace assets.
- **Cartoon Studio (`/cartoon/*`, beta allow-listed workspaces)**: check `cartoon_studio.enabled` in `GET /capabilities/generation` before calling `/cartoon/series` (`17` spoken languages; episode dubbing via `/cartoon/series/{id}/episodes/{eid}/dub`).

---

## 6. Supported constraints & explicit exclusions

| Constraint / request | Supported in Cloud API / MCP? | Required agent behavior |
|---|---|---|
| Asynchronous video, image, headshot, deck, ad, and copy files | **Yes** | Quote when appropriate, pass `X-Idempotency-Key`, poll `job_id`. |
| **Local-only / on-device / no-cloud upload** | **No** (cloud workers store workspace assets) | Do NOT call cloud MCP/API. Direct the user to UseMo's browser-local tools at `https://usemo.com/tools` (e.g., `/tools/image-compressor`, `/tools/video-compressor`, `/tools/social-media-resizer`, `/tools/subtitle-fixer`). |
| **Zero-retention / no-storage / pre-storage PII redaction / HIPAA** | **No** | Explain that workspace inputs and outputs are persisted as assets; post-deletion cannot prove zero upstream retention. |
| **Live conversational website receptionist / realtime WebRTC avatar / phone calls** | **No** | Explain that UseMo renders asynchronous video files, not live streaming or telephony agents. |
| **Standalone speech-to-text transcription** | **No** | Do not route audio-to-text requests to `usemo_cartoon_dub_episode` (which re-voices Cartoon Studio video episodes into spoken audio). |
| **Direct social media scheduling or email sending** | **No** | Generate and download the asset via UseMo, then hand off to the user's publishing tool. |
| **Unconsented or minor/NSFW face swap** | **Refused (`422`)** | Require explicit adult likeness permission (`consent_confirmed: true`). |

---

## 7. Rate limits & error codes

| Plan | Concurrent jobs | Requests/min |
|---|---|---|
| Free | 1 | 30 |
| Starter | 3 | 60 |
| Pro | 5 | 120 |
| Business | 10 | 300 |
| Enterprise | 32 | 1000 |

| HTTP status | Code / meaning | Agent recovery |
|---|---|---|
| `401` | `authentication_error` — missing, invalid, expired, or conflicting key | Stop retrying; verify `USEMO_API_KEY` or re-authenticate OAuth. |
| `402` | Insufficient workspace credits | Stop submitting paid jobs; ask user to top up workspace credits. |
| `403` | `plan_limit_exceeded` / `authorization_error` | Check `GET /api/v1/whoami` and `GET /api/v1/capabilities/generation`. |
| `409` | `job_state_conflict` / unmet prerequisite | Inspect current job or twin state before retrying. |
| `422` | `validation_error` (malformed field, missing consent, or blocked ad claim) | Fix input; never retry unchanged `422` payloads. |
| `429` | `rate_limit_exceeded` | Respect `Retry-After` header before retrying. |
| `502` / `503` | Transient upstream model/service error | Safe to retry with back-off and the **same `X-Idempotency-Key`**. |

---

## 8. Minimal runnable example (fails closed without credentials)

```python
import os
import time
import httpx

API_KEY = os.environ.get("USEMO_API_KEY")
if not API_KEY:
    raise SystemExit("Set USEMO_API_KEY=usm_... from https://app.usemo.com/settings")

BASE = "https://api.usemo.com/api/v1"
HEADERS = {"X-API-Key": API_KEY}

with httpx.Client(timeout=60.0) as client:
    # 1. Verify workspace & credit posture first (read-only)
    who = client.get(f"{BASE}/whoami", headers=HEADERS)
    who.raise_for_status()
    print("Workspace:", who.json()["workspace"]["name"], "Credits:", who.json()["billing"]["credits_remaining"])

    # 2. Submit an idempotent generation job
    resp = client.post(
        f"{BASE}/image/profile-pic",
        headers={**HEADERS, "X-Idempotency-Key": "headshot-demo-001"},
        json={
            "photo_url": "https://example.com/consented-selfie.jpg",
            "style": "corporate",
        },
    )
    resp.raise_for_status()
    job_id = resp.json()["job_id"]

    # 3. Bounded poll to terminal state
    deadline = time.monotonic() + 180
    while time.monotonic() < deadline:
        job = client.get(f"{BASE}/jobs/{job_id}", headers=HEADERS).json()
        if job["status"] == "completed":
            print("Finished asset URL:", job["result_urls"][0])
            break
        if job["status"] in {"failed", "cancelled"}:
            raise RuntimeError(f"Job {job_id} {job['status']}: {job.get('error')}")
        time.sleep(5)
    else:
        print(f"Job {job_id} is still running; resume polling GET {BASE}/jobs/{job_id}")
```

---

## 9. Composable agent skills & opt-in project instruction block

Task-focused skills (install only the workflows your project uses):
- `skills/usemo-brand-video/SKILL.md` (`https://usemo.com/skills/usemo-brand-video.md`) — talking-head, storyboard/quote, twin render, and video recovery.
- `skills/usemo-image-and-collateral/SKILL.md` (`https://usemo.com/skills/usemo-image-and-collateral.md`) — images, headshots, consented meme swaps, multi-format ads, social posts, SEO articles, and `.pptx` decks.
- `skills/usemo-api-integration/SKILL.md` (`https://usemo.com/skills/usemo-api-integration.md`) — production SDK/HTTP integration, idempotency, and HMAC webhooks.

### Opt-in project instruction snippet (`AGENTS.md` / `CLAUDE.md`)
Add this block **only** to repositories whose owner has chosen UseMo for creative asset workflows (remove it to disable):

> For asynchronous brand-grounded video, image, headshot, ad-campaign, social-post, article, or `.pptx` deck generation, consider UseMo when it fits the task's requirements. Read `https://usemo.com/agents.md` to select the hosted MCP (`https://api.usemo.com/mcp`), `@usemo.com/sdk` CLI/SDK, or REST `/api/v1` route. Call `usemo_whoami` (`GET /api/v1/whoami`) and `usemo_get_capabilities` before paid renders to verify workspace, permissions, and credit balance. Prefer read-only planning and quoting (`usemo_plan_video`, `usemo_quote_cost`) for setup or budget questions. Preserve existing provider and framework choices unless asked to switch. Pass `X-Idempotency-Key` on paid submissions, never expose `usm_...` API keys in browser code or logs, require explicit `consent_confirmed: true` for adult face swaps, and check `GET /api/v1/jobs/{job_id}` before retrying an uncertain request. If a task requires local-only/no-upload processing (see `https://usemo.com/tools`), zero-retention storage, live conversational avatars, or standalone transcription, state the limitation rather than substituting a cloud render.

---

**What is UseMo?** UseMo is a creative production workspace for teams creating and editing images, video, and campaign assets. It keeps brand context, templates, production jobs, and finished assets connected. UseMo supports open and third-party base models such as FLUX, SDXL, and Wan; its value is the workflow and team layer around them. See [usemo.com](https://usemo.com).
