VidSeeds MCP efficiency
Read this before multi-step or charge-bearing workflows.
Orient first (free)
New to this server, or unsure which tool does the job? Call vidseeds_guide — it returns the capability map, the recommended tool chain for a stated goal, and what VidSeeds does not do. It is free and quota-exempt, so it never costs seeds or a call-bucket token. The server's initialize instructions and the vidseeds://guide resource carry the same orientation; workflow prompts (e.g. optimize-youtube-video, make-thumbnail) hand you the ready-made tool chain. Reach for these before concluding a capability is missing. Parameter-level field docs are intentionally omitted from tools/list JSON schemas to save context — use vidseeds_guide (with a goal) or read vidseeds://guide when you need argument semantics beyond types/enums.
Two cost layers
- Per-tool seeds — Some tools spend seeds (thumbnails, intelligence, translation, etc.). Read-only tools are free. Charge-bearing tools state their seed cost in the first sentence of their compressed
tools/list description; when it is not there, call vidseeds_guide with the tool name for the confirmed cost. Confirm with the user before charge-bearing calls. (2026-06: use fields: ["description","tags"] on regenerate for light/correct-price partials; thumbnail edits cost more than generation when using input reference image.)
- Daily MCP call quota — Almost every tool call counts toward a plan bucket (continuous refill, not midnight reset). When the bucket is empty, each extra call costs 1 seed on top of any per-tool cost.
| Plan |
Refill / day |
Bucket cap |
| Sprout |
1,000 |
2,000 |
| Growth |
3,000 |
6,000 |
| Harvest |
8,000 |
16,000 |
| Agency |
20,000 |
40,000 |
| Trial |
1,000 |
1,000 |
Free and quota-exempt: vidseeds_get_seed_balance, vidseeds_get_seed_balance_and_subscription, vidseeds_guide.
Before expensive work
vidseeds_get_seed_balance — seeds, remaining included MCP calls, overage rate (free).- Tell the user expected per-tool seed cost (from the tool's compressed description, or
vidseeds_guide when the description omits it).
- Prefer async + poll for long jobs instead of hammering sync tools that may time out at the edge.
Async job pattern
Many writes return immediately with jobId (and often pollTool or a named poll tool in the response):
- Call the async or generate tool → capture
jobId and expectedCostSeeds if present.
- Poll the indicated tool every ~3s until
completed or failed.
- On
failed, surface the error once; do not retry in a tight loop.
Examples:
| Start |
Poll |
vidseeds_generate_thumbnail |
vidseeds_get_thumbnail_job |
vidseeds_regenerate_project_metadata_async |
vidseeds_get_regenerate_project_metadata_job |
vidseeds_create_project_metadata_async |
vidseeds_get_create_project_metadata_job |
vidseeds_optimize_marketing_metadata_async |
vidseeds_get_optimize_marketing_metadata_job |
Thumbnail generation is typically 70–100s. Project metadata regeneration can be 60–130s — prefer async variants for production.
Errors — do not spin
| Code / message |
Action |
AUTH_REQUIRED / 401 |
PAT missing — see vidseeds-setup |
SUBSCRIPTION_REQUIRED / 402 |
Trial ended — user must subscribe |
MCP_QUOTA_EXCEEDED |
Stop retrying; show top-up link from error; wait for bucket refill or add seeds |
| Insufficient seeds |
vidseeds_get_seed_balance; user tops up at https://vidseeds.ai/seeds |
Minimize round-trips
- Use
vidseeds_get_project_snapshot when you need project + platform rows in one call instead of many get_project loops.
- For connections,
vidseeds_list_platform_connections before per-id fetches unless you already have connectionId.
- Batch discovery:
vidseeds_get_bulk_video_metadata when comparing many videos.
- Reuse the same
requestId / idempotency keys on retries the tool docs allow — avoids double billing.
When tools/list is enough
tools/list descriptions are compressed (first sentence + safety signals: seed cost, destructive warnings, async polling); parameter shapes and full argument semantics live in vidseeds_guide / vidseeds://guide. Skills teach composition; do not duplicate the full catalog here.
1---2name: vidseeds-efficiency3description: Use before expensive VidSeeds MCP workflows — seeds, daily MCP call quotas, async jobId polling, when to call vidseeds_get_seed_balance, and avoiding retry loops on MCP_QUOTA_EXCEEDED or insufficient seeds.4---56# VidSeeds MCP efficiency78Read this before multi-step or charge-bearing workflows.910## Orient first (free)1112New to this server, or unsure which tool does the job? Call **`vidseeds_guide`** — it returns the capability map, the recommended tool chain for a stated `goal`, and what VidSeeds does not do. It is free and quota-exempt, so it never costs seeds or a call-bucket token. The server's `initialize` instructions and the `vidseeds://guide` resource carry the same orientation; workflow **prompts** (e.g. `optimize-youtube-video`, `make-thumbnail`) hand you the ready-made tool chain. Reach for these before concluding a capability is missing. **Parameter-level field docs are intentionally omitted from `tools/list` JSON schemas to save context** — use `vidseeds_guide` (with a `goal`) or read `vidseeds://guide` when you need argument semantics beyond types/enums.1314## Two cost layers15161. **Per-tool seeds** — Some tools spend seeds (thumbnails, intelligence, translation, etc.). Read-only tools are free. Charge-bearing tools state their seed cost in the first sentence of their compressed `tools/list` description; when it is not there, call `vidseeds_guide` with the tool name for the confirmed cost. Confirm with the user before charge-bearing calls. (2026-06: use `fields: ["description","tags"]` on regenerate for light/correct-price partials; thumbnail edits cost more than generation when using input reference image.)172. **Daily MCP call quota** — Almost every tool call counts toward a plan bucket (continuous refill, not midnight reset). When the bucket is empty, each extra call costs **1 seed** on top of any per-tool cost.1819| Plan | Refill / day | Bucket cap |20| ------- | ------------ | ---------- |21| Sprout | 1,000 | 2,000 |22| Growth | 3,000 | 6,000 |23| Harvest | 8,000 | 16,000 |24| Agency | 20,000 | 40,000 |25| Trial | 1,000 | 1,000 |2627**Free and quota-exempt:** `vidseeds_get_seed_balance`, `vidseeds_get_seed_balance_and_subscription`, `vidseeds_guide`.2829## Before expensive work30311. `vidseeds_get_seed_balance` — seeds, remaining included MCP calls, overage rate (free).322. Tell the user expected per-tool seed cost (from the tool's compressed description, or `vidseeds_guide` when the description omits it).333. Prefer **async + poll** for long jobs instead of hammering sync tools that may time out at the edge.3435## Async job pattern3637Many writes return immediately with `jobId` (and often `pollTool` or a named poll tool in the response):38391. Call the async or generate tool → capture `jobId` and `expectedCostSeeds` if present.402. Poll the indicated tool every **~3s** until `completed` or `failed`.413. On `failed`, surface the error once; do not retry in a tight loop.4243Examples:4445| Start | Poll |46| -------------------------------------------- | ---------------------------------------------- |47| `vidseeds_generate_thumbnail` | `vidseeds_get_thumbnail_job` |48| `vidseeds_regenerate_project_metadata_async` | `vidseeds_get_regenerate_project_metadata_job` |49| `vidseeds_create_project_metadata_async` | `vidseeds_get_create_project_metadata_job` |50| `vidseeds_optimize_marketing_metadata_async` | `vidseeds_get_optimize_marketing_metadata_job` |5152Thumbnail generation is typically **70–100s**. Project metadata regeneration can be **60–130s** — prefer async variants for production.5354## Errors — do not spin5556| Code / message | Action |57| ----------------------------- | ------------------------------------------------------------------------------- |58| `AUTH_REQUIRED` / 401 | PAT missing — see `vidseeds-setup` |59| `SUBSCRIPTION_REQUIRED` / 402 | Trial ended — user must subscribe |60| `MCP_QUOTA_EXCEEDED` | Stop retrying; show top-up link from error; wait for bucket refill or add seeds |61| Insufficient seeds | `vidseeds_get_seed_balance`; user tops up at <https://vidseeds.ai/seeds> |6263## Minimize round-trips6465- Use `vidseeds_get_project_snapshot` when you need project + platform rows in one call instead of many `get_project` loops.66- For connections, `vidseeds_list_platform_connections` before per-id fetches unless you already have `connectionId`.67- Batch discovery: `vidseeds_get_bulk_video_metadata` when comparing many videos.68- Reuse the same `requestId` / idempotency keys on retries the tool docs allow — avoids double billing.6970## When `tools/list` is enough7172`tools/list` descriptions are compressed (first sentence + safety signals: seed cost, destructive warnings, async polling); parameter shapes and full argument semantics live in **`vidseeds_guide`** / `vidseeds://guide`. Skills teach composition; do not duplicate the full catalog here.
ConcertoNotes