@vibevo/mcp

@vibevo/mcp — VibeVO MCP server (AIPROD-204)

MCP server that exposes the VibeVO Public API as agent tools, so AI agents (Claude Desktop, IDE agents, custom runners) can discover and operate VibeVO programmatically.

Standalone on purpose. This package lives at repo root (/mcp), outside the npm workspace globs (packages/*, services/*, apps/*), so it does NOT pull @modelcontextprotocol/sdk into the monorepo lockfile or the turbo build. Install and build it on its own. When the SDK is added to the root lockfile it can graduate to services/mcp.

Tools

Tool	Wraps	Scope
vibevo_whoami	GET /public/me	any valid key
vibevo_list_offers	GET /public/offers	read
vibevo_list_my_posts	GET /public/posts	read
vibevo_list_campaigns	GET /public/campaigns	read
vibevo_get_campaign	GET /public/campaigns/{id}	read
vibevo_get_campaign_analytics	GET /public/analytics/campaigns/{id}	read
vibevo_list_campaign_posts	GET /public/campaigns/{id}/posts	read
vibevo_list_campaign_creators	GET /public/campaigns/{id}/creators	read
vibevo_list_campaign_tracking_links	GET /public/campaigns/{id}/tracking-links	read
vibevo_get_wallet	GET /public/wallet	read
vibevo_list_wallet_transactions	GET /public/wallet/transactions	read
vibevo_list_factories	GET /public/factories	read
vibevo_list_factory_accounts	GET /public/factories/{id}/accounts	read
vibevo_list_factory_posts	GET /public/factories/{id}/posts	read
vibevo_create_factory	POST /public/factories	write †
vibevo_add_factory_items	POST /public/factories/{id}/items	write †
vibevo_patch_factory_account	PATCH /public/factories/{id}/accounts/{aid}	write †
vibevo_refresh_factory_account	POST /public/factories/{id}/accounts/{aid}/refresh	write †
vibevo_submit_post	POST /public/posts	write

Scopes are coarse: read covers every GET, write every mutation. A key always has read; write is granted only if the account has write access. † Content Factories are a separate product feature and their writes must be enabled separately from general write access (they spend money on scraping) — expect 403 if not. vibevo_refresh_factory_account runs a paid scrape and is capped at once per hour per account (429 REFRESH_COOLDOWN, with retryAfterSec). tracking_links rows carry uniqueClicks (bot-filtered distinct-device count, not raw hits). There is no test/sandbox mode — all keys are live.

New endpoints map 1:1 to new tools — ideally generated from the public OpenAPI document (/api/public-docs) in a later iteration.

Setup

cd mcp
npm install
npm run build

Run

VIBEVO_API_KEY=vibevo_live_xxxxxxxxxxxx.<secret> \
VIBEVO_API_BASE_URL=https://api.vibevo.io \
node dist/index.js

Mint the API key in the VibeVO cabinet (POST /api/v1/api-keys) with the scopes the agent needs.

Claude Desktop config

Once the package is published to npm, point the client at it via npx (no local checkout needed):

{
  "mcpServers": {
    "vibevo": {
      "command": "npx",
      "args": ["-y", "@vibevo/mcp"],
      "env": { "VIBEVO_API_KEY": "vibevo_live_..." }
    }
  }
}

For local development against a checkout, use the built entrypoint instead:

{
  "mcpServers": {
    "vibevo": {
      "command": "node",
      "args": ["/absolute/path/to/VibeVO/mcp/dist/index.js"],
      "env": { "VIBEVO_API_KEY": "vibevo_live_..." }
    }
  }
}

Env

Var	Required	Default
VIBEVO_API_KEY	yes	—
VIBEVO_API_BASE_URL	no	https://api.vibevo.io

Publishing to the MCP registry

server.json is the manifest for the official MCP Registry and targets the 2025-12-11 schema. The server name is io.vibevo/vibevo; ownership of the io.vibevo namespace is verified through the vibevo.io DNS zone. The npm package declares the same name in mcpName, which the Registry checks during publication.

Prerequisites

• Publish the npm package first. Run npm publish from mcp/. Keep the npm package version, the MCP runtime version and both versions in server.json aligned.
• Own the namespace. Publish the Registry public key as a TXT record on vibevo.io; never commit the private key.

Steps (run manually)

# 1. Install the official publisher CLI.
brew install mcp-publisher

# 2. Authenticate after the DNS TXT record has propagated.
#    The environment variable contains the raw private-key hex, not a PEM path.
mcp-publisher login dns --domain vibevo.io --private-key "$MCP_REGISTRY_PRIVATE_KEY"

# 3. Validate + publish using this manifest.
cd mcp
mcp-publisher validate ./server.json
mcp-publisher publish ./server.json

After publication, verify the entry through the Registry API.

DoD e2e (AIPROD-204)

Agent runs vibevo_list_campaigns → picks a campaign → vibevo_get_campaign_analytics, authenticated by a live key scoped to the caller's own campaigns.