MCP for AI agents
MCP gives your AI client tools to work with VibeVO: read accounts, campaigns and posts, manage content factories and prepare reports.
Connect a client
You need Node.js 20+ and a VibeVO API key. Viewing requires the read scope; changes require write and access to the relevant feature. Create an API key.
Client configuration
Codex · CLI / IDE
Add this to ~/.codex/config.toml. Set VIBEVO_API_KEY in the environment that starts Codex. This works with the CLI and IDE extension. Restart the client and check /mcp.
[mcp_servers.vibevo]
command = "npx"
args = ["-y", "@vibevo/mcp@latest"]
env_vars = ["VIBEVO_API_KEY"]Claude Desktop / Cursor
Claude Desktop: Settings → Developer → Edit Config. Cursor: personal ~/.cursor/mcp.json. Merge the block into your existing configuration, replace REPLACE_WITH_YOUR_API_KEY locally and restart the client.
{
"mcpServers": {
"vibevo": {
"command": "npx",
"args": [
"-y",
"@vibevo/mcp@latest"
],
"env": {
"VIBEVO_API_KEY": "REPLACE_WITH_YOUR_API_KEY"
}
}
}
}If Windows cannot find npx, use command: cmd and args: ["/c", "npx", "-y", "@vibevo/mcp@latest"].
Client documentation · Claude DesktopClient documentation · Cursor
Verify the connection
Ask the agent to call vibevo_whoami and verify the key owner and permissions. For 401, check your key; for 403, check scopes and feature access.
Capabilities and tools
Tool availability depends on the published package, role and key permissions. This is a reference; the connected server supplies the exact input schemas.
Identity and wallet
Tool reference 3
vibevo_whoamiReadvibevo_get_walletReadvibevo_list_wallet_transactionsRead
Social accounts and verification
Tool reference 10
vibevo_list_social_accountsReadvibevo_get_social_account_verificationReadvibevo_get_social_account_statsReadvibevo_add_social_accountWritevibevo_connect_social_accountWritevibevo_start_social_account_verificationWritevibevo_check_social_account_verificationWritevibevo_start_social_account_stats_sessionWritevibevo_upload_social_account_statsWritevibevo_refresh_social_account_statsWrite
Campaigns and posts
Tool reference 14
vibevo_list_offersReadvibevo_list_my_postsReadvibevo_list_campaignsReadvibevo_get_campaignReadvibevo_get_campaign_analyticsReadvibevo_list_campaign_postsReadvibevo_list_campaign_creatorsReadvibevo_list_campaign_tracking_linksReadvibevo_list_campaign_post_proofsReadvibevo_get_campaign_post_proofReadvibevo_download_campaign_proofs_zipReadvibevo_list_my_post_proofsReadvibevo_get_my_post_proofReadvibevo_submit_postWrite
Factories, accounts and tags
Tool reference 11
vibevo_list_factoriesReadvibevo_get_factory_summaryReadvibevo_list_factory_accountsReadvibevo_list_factory_postsReadvibevo_get_factory_accountReadvibevo_create_factoryWritevibevo_patch_factoryWritevibevo_add_factory_itemsWritevibevo_patch_factory_accountWritevibevo_list_factory_tagsReadvibevo_list_factory_tag_groupsRead
Add a tag to an account
Tags belong to monitored factory accounts. Use them to filter accounts, their posts and aggregate statistics. Your tag list is shared across factories.
- Find a factory with vibevo_list_factories, then the account with vibevo_list_factory_accounts. Use factoryAccountId from the response, not a social-network ID.
- Read current tags. To add a tag, combine existing and new names without duplicates and send the full list to vibevo_patch_factory_account.
- Read the account again to verify. vibevo_list_factory_tags lists your available tags; vibevo_list_factory_tag_groups provides per-tag factory statistics.
A ready-to-use request to add a tag without removing existing tags. Replace the factory name, account and tag before sending.
Example arguments · replace the IDs and tags
{
"id": 1,
"factoryAccountId": 42,
"tags": [
"Brand",
"Autumn"
]
}Monitoring and tokens
Tool reference 9
vibevo_refresh_factory_accountWritevibevo_get_monitoring_walletReadvibevo_get_factory_creditsReadvibevo_get_factory_credit_usageReadvibevo_list_factory_credit_historyReadvibevo_update_factory_scan_settingsWritevibevo_set_factory_monitoringWritevibevo_refresh_factory_postWritevibevo_buy_monitoring_tokensWrite
Public reports
Tool reference 5
vibevo_list_factory_reportsReadvibevo_create_factory_reportWritevibevo_revoke_factory_reportWritevibevo_restore_factory_reportWritevibevo_delete_factory_reportWrite
ER and saves
ER = 100 × (likes + comments) / views, rounded to two decimals. It uses the latest complete observations of views, likes and comments. Aggregates use summed counters rather than an average of post percentages. ER is null with zero views or no complete observation. Saves and reposts are excluded from the formula.
Campaign lists, details, analytics, posts and creators return engagement with scope: accepted_video. Only accepted video posts are included; a post row covers that post and a creator row covers that account. Use engagement.views as the denominator: the existing totalViews may include other statuses or represent paid views.
Factories expose canonical ER in metrics.er (totals.er in a summary) and saves in metrics.saves. History points and snapshotBaseline contain the same fields. The existing top-level er retains its earlier semantics; new clients use the nested field. Missing new fields in an older response do not prove a measurement.
saves is a separate last-known counter. Automatic sources are TikTok collectCount and X bookmarkCount, only when the provider returns a valid value. Other platforms have no value without an actual measurement. 0 means measured zero; null means unavailable. Do not replace null with zero. Legacy campaign history does not prove raw views: new ER becomes available after a normal scan, without a mass paid rescan.
erCoverage and savesCoverage contain measuredPosts / totalPosts for the entire selected cohort before pagination. Partial coverage means a partial aggregate. updatedAt and savesUpdatedAt are the oldest included measurement times; null means unknown freshness. Carrying an old counter into a new snapshot does not refresh its time. ER and saves chart values are absolute snapshots, without a growth mode.
Report hiddenFields accepts saves: the server removes its count, coverage and measurement time. Hiding views, likes, comments or er also removes dependent ER; hiding posts removes coverage, and lastScanned removes measurement times. These rules apply to summaries, rows, history and baselines.
{
"engagement": {
"scope": "accepted_video",
"views": 100,
"likes": 0,
"comments": 0,
"er": 0,
"saves": null,
"erCoverage": { "measuredPosts": 1, "totalPosts": 2 },
"savesCoverage": { "measuredPosts": 0, "totalPosts": 2 },
"updatedAt": "2026-10-09T08:00:00.000Z",
"savesUpdatedAt": null
}
}Update MCP
The configuration above uses @latest: the published npm version, not a GitHub branch. If pinned to an old version, replace it with @latest, then stop and restart the MCP server or fully restart your AI client. Updating the website does not update an already running MCP process.
npm view @vibevo/mcp versionRefresh your client's tool list after restarting. Tag support requires vibevo_list_factory_tags and the tags parameter in vibevo_patch_factory_account (available since 0.3.0). A tool not yet published cannot be obtained by updating npm.
Agent prompt
Copy and send to your agent after connecting MCP. Includes documentation and npm links, plus rules for handling your data.
Was this article helpful?
Updated: 2026-09-23