Tool Catalog
The Vivreal MCP server exposes 69 tools across 11 modules. Every tool declares either readOnlyHint: true (safe to call without confirmation) or destructiveHint: true (mutation — your MCP client should render a confirmation prompt) so agents and human reviewers always know what a call will do.
Channel setup lives in the portal, not here
The MCP exposes tools for posting on, reading from, and syncing connected channels. It deliberately does not expose tools for activating/deactivating channels or connecting/disconnecting individual social accounts — those flows belong in the portal Integrations page, where the OAuth UX is consistent and the redirect_uri allowlist is owned. If list-channel-accounts returns an empty list, tell the user to connect the account in the portal first.
Counts
| Total tools | 69 |
Read-only (readOnlyHint: true) | 34 |
Destructive (destructiveHint: true) | 35 |
| Modules | 11 |
Scope Reference
Every tool requires one of three OAuth scopes. The hierarchy is read → write → admin.
| Scope | What it lets you do |
|---|---|
vivreal/cms.read | List, get, search anything inside the active group |
vivreal/cms.write | Plus: create, update, archive, delete content / channels / sites |
vivreal/cms.admin | Plus: invite/remove members, update group billing, manage CORS origins |
Pure-read tools accept any of the three. Write tools require cms.write or cms.admin. Admin tools require cms.admin.
Session (3 tools)
| Tool | Scope | Classification | What it does |
|---|---|---|---|
get-session-context | cms.read | Read-only | Returns the authenticated user, their groups, and the currently active group |
set-active-group | cms.read | Destructive (session) | Sets the active group for the session — required before any CMS call. Auto-refreshes the cached group list once on cache miss so newly-created groups become usable without reconnecting. |
refresh-session-context | cms.read | Read-only | Re-fetches the user's group list from Vivreal. Use after creating, deleting, or changing group membership in the portal during the same MCP session. Returns the same shape as get-session-context. |
Collections (9 tools)
Content types and their schemas. "Collections" in the Vivreal vocabulary are user-defined content schemas.
| Tool | Scope | Classification |
|---|---|---|
list-content-types | cms.read | Read-only |
get-content-type | cms.read | Read-only |
create-content-type | cms.write | Destructive |
update-content-type | cms.write | Destructive |
delete-content-type | cms.write | Destructive |
list-content-schemas | cms.read | Read-only |
list-content-tags | cms.read | Read-only |
duplicate-content-type | cms.write | Destructive |
get-content-field-types | cms.read | Read-only |
Content Objects (12 tools)
Instances of content types — blog posts, products, events, etc.
| Tool | Scope | Classification |
|---|---|---|
list-content | cms.read | Read-only |
create-content | cms.write | Destructive |
bulk-create-content (pro+) | cms.write | Destructive |
update-content | cms.write | Destructive |
delete-content | cms.write | Destructive |
update-content-publish-date | cms.write | Destructive |
bulk-update-content-publish-date (pro+) | cms.write | Destructive |
archive-content | cms.write | Destructive |
unarchive-content | cms.write | Destructive |
duplicate-content | cms.write | Destructive |
bulk-delete-content | cms.write | Destructive |
bulk-archive-content | cms.write | Destructive |
Media (5 tools)
Uploads + attachment management for collection objects.
| Tool | Scope | Classification |
|---|---|---|
get-upload-url | cms.write | Destructive |
list-content-media | cms.read | Read-only |
add-content-media | cms.write | Destructive |
delete-content-media | cms.write | Destructive |
reorder-content-media | cms.write | Destructive |
Calendar (1 tool)
| Tool | Scope | Classification |
|---|---|---|
list-events | cms.read | Read-only |
Dashboard (1 tool)
| Tool | Scope | Classification |
|---|---|---|
get-dashboard | cms.read | Read-only |
Sites (14 tools)
Vivreal-deployed websites — full lifecycle including deploys, versions, and DNS.
For hosted-by-us sites, deployment is triggered automatically by create-site via the EventHandler Step Function pipeline (GitHub branch → Amplify app → seed collections → build → domain associate → mark live). There is no separate "deploy" tool — poll get-site to watch the pipeline progress.
`pipelineStatus` is the source of truth for deploy progress
Use get-site-deployment-status to track a hosted-by-us deploy. It returns BOTH answers in one call:
- Primary —
pipelineStatus(andpipelineMessage,pipelineUpdatedAt,liveUrl): the authoritative end-to-end pipeline state, written by the EventHandler Step Function at every step. Same field the portal's deployment status badge reads. Always trust this first. - Secondary —
amplifyStatus,deploys[],previewUrl: best-effort detail from AWS Amplify'sListJobsAPI for the build job itself. Can returnamplifyStatus: nullwithdeploys: []even on a healthy, completed deploy (job-history propagation lag, IAM/branch-resolution gaps). An emptydeploys: []does NOT mean the pipeline failed.
get-site exposes the same primary fields under deployment.status / deployment.message if you want them as part of the broader site doc, but for poll-the-deploy use cases get-site-deployment-status is the right tool.
Poll every 30 seconds. A typical hosted-by-us deploy with a *.vivreal.io subdomain reaches pipelineStatus === "live" in 5–10 minutes; flag as stuck only past 15 minutes or when pipelineStatus lands in a failure state.
pipelineStatus enum
16 states emitted by the Step Function pipeline. Each in-progress state has its own user-facing label (the portal's deployment badge uses these verbatim).
pipelineStatus | User-facing label | Meaning |
|---|---|---|
queued | Waiting to start | Site created, Step Function not yet picked it up. |
seeding | Preparing content | Tenant DB being seeded with template collections + objects. |
creating_branch | Setting up your site | Forking the template GitHub branch. |
creating_app | Setting up hosting | Amplify app being provisioned. |
app_created | Configuring your site | Amplify app created, environment being configured. |
deploying | Publishing your site | Amplify build job running (longest step — 2–4 min). |
getting_url | Getting your web address | Resolving Amplify default URL after build. |
associating_domain | Connecting your domain | Submitting domain association to Amplify. |
checking_domain | Verifying your domain | Polling Amplify for domain verification. |
domain_connecting | Awaiting domain verification | Cert verification + DNS propagation in progress (custom domains). |
subdomain_updating | Updating address | Renaming the site's *.vivreal.io subdomain. |
live | Live | Site is reachable at liveUrl. Terminal-success state. |
failed | Something went wrong | Generic pipeline failure. Terminal. |
app_creation_failed | Hosting setup failed | Amplify app provisioning failed. Terminal. |
domain_failed | Domain setup failed | Custom-domain association failed. Terminal. |
sync_conflict | Needs your attention | Sync state needs user intervention. |
Source of enum + labels: Vivreal_Portal_Mobile/src/components/Sites/Client/DeploymentStatusBadge.tsx. Source of pipeline state writes: Vivreal_EventHandler/src/shared/* Step Function steps.
| Tool | Scope | Classification |
|---|---|---|
list-sites | cms.read | Read-only |
get-site | cms.read | Read-only — full site doc. deployment.status mirrors pipelineStatus from get-site-deployment-status. For poll-the-deploy use cases, prefer get-site-deployment-status (it returns the same pipeline state plus Amplify build detail). |
create-site | cms.write | Destructive (external — auto-triggers Step Function deploy for hosted-by-us mode) |
update-site | cms.write | Destructive |
delete-site | cms.write | Destructive (external — tears down Amplify branch + seeded collections). Never call to "clean up" a deploy that appears stuck until pipelineStatus lands in a failure state — empty deploys: [] from the Amplify side does not mean failed. |
check-domain | cms.read | Read-only — Route53 apex-domain purchase availability + Stripe pricing. Not for Vivreal subdomain checks — use check-subdomain for that. |
check-subdomain | cms.read | Read-only — Vivreal subdomain availability for the active group |
get-site-deployment-status | cms.read | Read-only — returns BOTH the authoritative pipelineStatus (from Mongo, written by the Step Function — see callout above for the 16-state enum) AND best-effort amplifyStatus + deploys[] from Amplify ListJobs. Use this to poll deploy progress after create-site. |
connect-custom-domain | cms.write | Destructive (external — attaches a user-owned domain to a deployed site's Amplify app; returns DNS records for the registrar) |
check-custom-domain-status | cms.read | Read-only — poll Amplify domain-association status (cert verification + DNS propagation) |
remove-custom-domain | cms.write | Destructive (external — detaches custom domain, reverts to *.vivreal.io subdomain) |
list-site-versions | cms.read | Read-only |
get-site-version | cms.read | Read-only |
revert-site-version | cms.write | Destructive (content rollback only — does not redeploy) |
Channels / Integrations (10 tools)
External platforms — X, LinkedIn, Instagram, Facebook, TikTok, Mailchimp, Stripe.
Channels in Vivreal are multi-account: a single LinkedIn integration on one group can hold several connected LinkedIn accounts (e.g. one personal account that admins three Company Pages). Posting tools accept an optional accountId (from list-channel-accounts) so agents can pick which account a post goes from. Omitting it falls back to the integration's default group account.
| Tool | Scope | Classification |
|---|---|---|
list-channel-posts | cms.read | Read-only |
list-channel-accounts | cms.read | Read-only — connected accounts on a channel for the active group. For LinkedIn, exposes organizations[] (Company Pages the user admins) per account; for Facebook, exposes pages[]. Sensitive credentials stripped server-side. |
get-channel-info | cms.read | Read-only |
get-channel-status | cms.read | Read-only — for a focused account view, prefer list-channel-accounts. |
list-available-channels | cms.read | Read-only |
get-channel-post-analytics | cms.read | Read-only — analytics are scoped to the post's bound accountId (the account that created it). Posts predating per-account binding fall back to the integration's default token. |
create-channel-post | cms.write | Destructive (external — live post). Accepts optional accountId and (LinkedIn-only) targetOrgUrn for Company Page publishing. Pass publishDate (ISO 8601) to schedule. |
update-channel-post | cms.write | Destructive (external — live edit). The accountId binding is immutable — to rebind to a different account, delete and recreate. |
delete-channel-post | cms.write | Destructive (external — live delete) |
sync-channel (pro+) | cms.write | Destructive (external — rebuild from upstream). Sync is per-integration; all connected accounts on the channel are refreshed in one call. |
No channel-setup tools
The MCP no longer exposes activate-channel, deactivate-channel, connect-channel-account, or disconnect-channel-account. Those endpoints either didn't exist upstream (they 404'd in production) or stepped on the portal's OAuth flow. Channel setup belongs in the portal Integrations page.
Stripe (4 tools)
Read-only Stripe surface. Users initiate payouts, checkouts, and order fulfillment through the Vivreal portal UI where they're fully authenticated — those operations are not exposed to AI agents.
| Tool | Scope | Classification |
|---|---|---|
get-customer-portal | cms.read | Read-only (URL only) |
get-subscription-info | cms.read | Read-only |
list-stripe-orders | cms.read | Read-only |
get-stripe-balance | cms.read | Read-only |
Group Management (7 tools)
| Tool | Scope | Classification |
|---|---|---|
get-group-info | cms.read | Read-only |
get-group-usage | cms.read | Read-only — current group usage against tier caps, with per-resource progress bars, over-cap callouts, and estimated overage charges for eligible tiers. Free-tier zero-cap resources (e.g. AI agent actions) render as "Not in this tier" rather than unlimited. |
update-group | cms.admin | Destructive |
list-group-members | cms.read | Read-only |
invite-member | cms.admin | Destructive (sends email) |
remove-member | cms.admin | Destructive |
update-member-role | cms.admin | Destructive |
Docs (3 tools)
The MCP server can search and read this very documentation site, so agents can self-orient before calling tools.
| Tool | Scope | Classification |
|---|---|---|
search-vivreal-docs | cms.read | Read-only |
read-vivreal-doc | cms.read | Read-only |
list-related-vivreal-docs | cms.read | Read-only |
Tier Gating
A few advanced tools are gated to higher tiers and only appear in tools/list for users whose active group qualifies:
bulk-create-content— pro and abovebulk-update-content-publish-date— pro and abovesync-channel— pro and above
Calling a gated tool from a lower tier returns a clean MCP error explaining the upgrade requirement.
Workflow Prompts
In addition to tools, the server ships 8 guided prompts that orchestrate multi-step workflows:
audit-group-setupcreate-content-plandiagnose-failed-postimport-data-wizardlaunch-content-everywherepost-to-all-socialssetup-integration-checklistsite-builder-guide
Run them via your MCP client's prompts/list and prompts/get methods.
Resources
The server exposes 16 MCP resources — 3 static and 13 templated — for structured reads. Resources are pre-formatted views of group state that often bundle data which would otherwise require multiple tool calls to assemble. Discoverable via resources/list (static) and resources/templates/list (templated).
Static (3)
| URI | Returns |
|---|---|
vivreal://field-types | All supported schema field types with their constraints |
vivreal://content-types | Active group's content types |
vivreal://channels | Channel manifests for all platforms Vivreal supports |
Templated (13)
Substitute {placeholders} with real IDs:
| URI Template | Returns |
|---|---|
vivreal://groups/{groupId} | Group settings + metadata |
vivreal://groups/{groupId}/dashboard | Usage, quotas, recent activity |
vivreal://groups/{groupId}/audit?start=&end= | Audit log (ISO date params; retention varies by tier) |
vivreal://groups/{groupId}/content-types | All schemas in this group |
vivreal://groups/{groupId}/content-types/{contentTypeId} | One schema in detail |
vivreal://groups/{groupId}/content-types/{contentTypeId}/items?search=&page=&limit=&sort= | Paginated content items |
vivreal://groups/{groupId}/content-types/{contentTypeId}/items/{itemId} | One content item |
vivreal://groups/{groupId}/content-types/{contentTypeId}/items/{itemId}/versions | Version history (count limited by tier) |
vivreal://groups/{groupId}/sites | All sites in this group |
vivreal://groups/{groupId}/sites/{siteId} | One site |
vivreal://groups/{groupId}/channels | Group's connected channels with status |
vivreal://groups/{groupId}/channels/{channelType}/posts | Channel post history |
vivreal://channels/{channelType} | Channel manifest (capabilities, auth requirements) |
Prefer resources over the equivalent list tools when you want pre-formatted, structured data for display or analysis. Use tools when you need to mutate state or apply filtering not exposed by the resource URI.