@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_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 registry manifest (official server.json schema, io.modelcontextprotocol.registry format). It declares the server name (io.vibevo/vibevo), version, the npm package, the stdio transport and the runtime env vars (VIBEVO_API_KEY required+secret, VIBEVO_API_BASE_URL optional). Publishing is a manual step the owner runs; nothing here is automated.

Open decision (owner's call): WHICH registry and namespace to publish to — the official public modelcontextprotocol registry vs. a self-hosted one, and the exact reverse-DNS namespace (io.vibevo/… assumes control of the vibevo.io domain for DNS-based namespace verification; a io.github.<org>/… name would use GitHub verification instead). Adjust name in server.json to a namespace the org actually controls before publishing. Tracked as an open question on the Public API + MCP epic.

Prerequisites

• Publish the npm package first. package.json is publish-ready (public scope via publishConfig, a files allowlist, prepublishOnly build). The registry entry points at the npm package @vibevo/mcp, so that package must exist on npm (npm publish from mcp/) — or switch the packages entry to an mcpb/remote type if you don't want a public npm release. Keep the version in server.json in sync with package.json.
• Own the namespace. For io.vibevo/* you prove control of vibevo.io via a DNS TXT record; for io.github.<org>/* you authenticate the GitHub org/user. Pick whichever the org controls and set name accordingly.

Steps (run manually)

# 1. Install the publisher CLI (see the modelcontextprotocol registry docs for
#    the current install method / release binary).
#    e.g. via Go:  go install github.com/modelcontextprotocol/registry/cmd/mcp-publisher@latest

# 2. Authenticate for your namespace (DNS or GitHub verification).
mcp-publisher login dns --domain vibevo.io      # for an io.vibevo/* name
# or:  mcp-publisher login github               # for an io.github.<org>/* name

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

Schema caveat: the registry server.json schema is versioned and still evolving. This file targets the 2025-07-09 schema (camelCase fields: registryType, environmentVariables, isRequired, isSecret). If mcp-publisher rejects a field, re-check against the schema URL pinned in $schema and adjust — the field names/casing are the most likely thing to drift between schema versions.

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.