Tools and permissions
A practical map of the MCP scope families DesignGen uses for sessions, files, brand context, image generation, mockups, Creative Studio, approvals, and marketplace work.
Scope families
DesignGen grants are explicit. If an agent asks for a tool outside the approved scope set, the tool response includes a reauthorization action.
- sessions:read and sessions:write cover DesignGen session lookup and creation.
- files:read and files:write cover user file lookup and MCP upload handoff.
- brand:read and brand:write cover brand profile, assets, palette, fonts, and brand knowledge.
- image:generate and image:edit cover image generation, edits, vectorization, cutouts, and print-prep image processing.
- creative:read and creative:write cover Creative Studio sessions, carousel plans, status, and generated artifacts.
- approvals:write covers approval cards, workflow approvals, and approve or deny decisions.
- social:read discovers owned accounts, capabilities, posts and status. social:write imports studio images and saves drafts or schedule proposals. Agents prepare drafts; you approve publishing and scheduling in DesignGen.
Recovering missing permissions
When a tool returns insufficient_scope, reauthorization_required or forbidden, do not repeat it with the same token. HTTP 403 scope challenges and MCP mcp/www_authenticate metadata let compatible clients start incremental OAuth consent.
- Read requestedScopes and missingScopes from the response.
- Request the returned requestedScopes through your existing MCP client. Existing permissions are preserved. Keep the connection active. The client supplies fresh PKCE and state for OAuth consent.
- Retry the original tool call only after the new authorization completes.
Prepare social content for review
Use designgen_social read with resource accounts first. Instagram, TikTok, YouTube, LinkedIn, Google Business Profile, Facebook Pages, X and Pinterest are supported subject to the account’s returned availability and enabled channels.
- Use the exact connection ID. Inspect platform, displayName, connectionStatus, availability and capabilities. username may be null when a public handle is unavailable. Check availability before preparing a draft for that account.
- Generate content with DesignGen, then use designgen_social import_image with the owned sessionId, generationId and outputIndex. Put the returned artifactId in draft.mediaArtifactIds. Use only owned ready media. Import carousel slides one at a time.
- Use designgen_social draft for one chosen connectionId with caption, mediaArtifactIds, settings and a UUID idempotencyKey. Keep the same key when retrying an identical draft. Supply postId and revision to edit saved work. YouTube uploads can use settings.youtubeThumbnailArtifactId for an owned PNG or JPEG under 2 MB.
- scheduledAt is an absolute ISO time including UTC offset. timezone is the display timezone. This saves a schedule proposal, not a provider job. Share reviewUrl for approval of the exact content, destination and posting time.
- Read posts, review or status with the saved postId afterward. Report the returned state; a saved draft is never proof of scheduling or publication.
- Use read resource preferences or calendar to inspect defaults and planned work. Calendar query needs from and to ISO instants. set_default takes preference.platform and preference.connectionId; null clears it. Existing saved destinations do not change.
Inspect the inbox and prepare reviewed actions
workspace_read and workspace_prepare share an options envelope: domain, operation, connectionId, input, recordId, revision and idempotencyKey as needed. All native targets come from an owned observed source; never invent provider identifiers.
- With domain engagement, workspace_read supports capabilities, history, comments, conversations, post_metrics, account_metrics, automation_logs, records and record. History requires connectionId. Comments use input.sourceId from a returned post; reply threads also use commentSourceId where supported. Conversations are Instagram only.
- History is paginated and may be incomplete. Keep pagination cursors, data freshness, reporting periods and missing metric definitions explicit. Views, reach and engagement do not establish sales. Google Business history and metrics are unavailable through this provider.
- workspace_prepare with operation prepare needs a UUID idempotencyKey and input.kind plus sourceId. Reply, private_reply and message use message; message can use a recipientId returned in its conversation when recipients are ambiguous. moderation uses action. automation uses keywords and message; verify deliveryMode, since supported platforms use different public or private replies.
- Save changes with operation edit, recordId and the current revision. workspace_apply accepts only options {domain, recordId, revision}. Show its complete server-built preview and ask for explicit consent to that exact action, then use designgen_approvals decide. It always requires a per-call approval; workflow grants and autonomy cannot cover it. The existing decision tool relies on the assistant truthfully relaying consent. An accepted receipt does not prove delivery.
- Inspect saved records and activity after review. A failed action was rejected; fix its account or input and prepare a fresh review. An unknown result must be reconciled before another attempt, because it may already have happened.
- For an existing YouTube video, obtain its sourceId from engagement history. Use domain marketing, operation prepare and input {kind: thumbnail, sourceId, artifactId}. Read record or preview afterward. The owner reviews the saved image, video and channel before replacement. No thumbnail experiments are exposed.
- With domain reviews, read capabilities first: Google reviews use separate direct consent and may require application setup. Read accounts, locations with input.accountId, and reviews with input.locationId; use returned owned IDs and forward input.cursor. Read reconcile with recordId/revision to check an unknown result without sending again. Publishing authorization does not grant review access.
- Prepare a Google business reply with domain reviews, input {kind: reply, sourceId, message}; delete_reply proposes removing only the business reply. Review the exact saved source and reply before workspace_apply approval. The customer’s review is never deleted. Saved records remain readable when Google is disconnected.
- Advertising reads use domain advertising: capabilities, accounts, campaigns, adgroups, ads, insights, records, record, preview and reconcile. Prepare campaign/activate/pause/budget proposals with owned account/source/image IDs and explicit creative, HTTPS destination, integer budgetMicros/currency/lifetime period, maxBidMicros/biddingType, targeting and dates. Connected accounts grant no spending authority. Creation stays paused; activation is a separately reviewed action. Incomplete context blocks approval.
- SocialPost publishing, scheduling and cancellation remain human-only in DesignGen. workspace_apply does not expose those operations. Approval of a monitor’s delivery rule does not grant consent to future rule changes. Unknown external outcomes require inspection rather than replay.