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.