vibewatch-mcp

Connect any MCP client to your Vibewatch community-sentiment data.

Vibewatch's MCP server exposes eight read-only tools — seven over your organization's data (sentiment overview, sentiment trend, message search, daily insights, weekly reports, market context, and org details) plus public Stacks ecosystem sentiment. This package is a thin stdio bridge to that server: it wraps mcp-remote with the Vibewatch server URL and auth handling built in, plus a one-command setup for Buzz agents.

Use with Claude

Claude connects to the hosted server directly, so there's nothing to install:

• Claude (web, desktop, Cowork): add a custom connector in Claude's connector settings with the URL https://api.vibewatch.io/mcp/, leave the OAuth client ID and secret blank, then click Connect.

• Claude Code: run claude mcp add --transport http vibewatch https://api.vibewatch.io/mcp/, then /mcp to sign in. If you've already run connect-buzz or installed the plugin, skip this: Claude Code already has Vibewatch, and adding it again mounts the same tools twice.

Connecting opens a Vibewatch sign-in page. Sign in, pick the organization Claude can read, and approve. Claude can then read that organization's data through the eight tools below, none of which change anything.

Before you connect:

• MCP access is opt-in per organization. An owner or admin enables it in app.vibewatch.io → Settings → API Access. After that, any member of the organization can connect, including viewers.

• It's available on every plan, including the free trial.

• Revoke Claude's access any time from Settings → API Access, or disconnect it in Claude.

Try "What's the vibe in my community this week?", "Summarize our latest weekly Vibewatch report", or "Find negative Discord messages from the last 7 days."

ChatGPT connects to the same server: install Vibewatch from the ChatGPT plugin directory.

Related MCP server: Feedback Synthesis MCP

Use with Buzz

Two commands, one browser approval:

npm install -g vibewatch-mcp
vibewatch-mcp connect-buzz

connect-buzz signs you in to Vibewatch in the browser (no key to mint or copy), caches the sign-in for headless reuse, then registers the bridge in every agent harness it finds on your machine — Claude Code, Codex, and Goose. Restart your Buzz agents and they can answer questions from your community data.

Requires Node 18+. MCP access is opt-in per organization — an owner or admin enables it in app.vibewatch.io → Settings → API Access.

Worth knowing:

• The registration is user scope: every session of a configured harness on your machine can query Vibewatch, not just Buzz-spawned ones. The data is read-only community sentiment for your organization.

• To switch organizations, run vibewatch-mcp connect-buzz --reset.

• After upgrading vibewatch-mcp, run connect-buzz once more — the cached sign-in is keyed to the bundled mcp-remote version.

• To undo: claude mcp remove --scope user vibewatch, codex mcp remove vibewatch, or delete the extensions.vibewatch entry from ~/.config/goose/config.yaml (Windows: %APPDATA%\Block\goose\config\config.yaml). Revoke the app's access any time from Settings → API Access.

For the full Vibewatch-on-Buzz install — report delivery into a channel plus a ready-made @vibewatch persona — open the Buzz tile under Settings → Reports in app.vibewatch.io and follow the setup walkthrough.

Headless / CI: use a key instead

Where a browser sign-in isn't possible, an org-scoped key works everywhere the bridge runs:

1. In app.vibewatch.io, open Settings → API Access and mint a key. Keys start with vw_mcp_ and are shown once — store them like passwords.

2. Pass it to connect-buzz (vibewatch-mcp connect-buzz --key vw_mcp_...) or set it directly where the bridge runs:

claude mcp add --scope user vibewatch -e VIBEWATCH_MCP_KEY=vw_mcp_... -- vibewatch-mcp

Keys are org-scoped and read-only; revoke them any time from the same screen.

Use with any stdio MCP client

Generic client config (Claude Desktop and compatible). GUI apps on macOS start with a minimal PATH, so use the absolute path from which vibewatch-mcp:

{
  "mcpServers": {
    "vibewatch": {
      "command": "/opt/homebrew/bin/vibewatch-mcp"
    }
  }
}

With no VIBEWATCH_MCP_KEY set, the bridge uses the cached browser sign-in (run connect-buzz once to create it — or the client's first connection opens the sign-in page itself). Add an env block with VIBEWATCH_MCP_KEY to use a key instead.

The bridge owns sign-in tabs: mcp-remote's own browser auto-open is disabled under the bridge, and the bridge opens the sign-in page itself — at most one tab machine-wide per sign-in, however many agent sessions are running. That covers mid-session re-auth too (a revoked or expired sign-in with many live sessions opens one tab, not one per session). If a sign-in page is never completed, the bridge won't open another one: later spawns (a client restarting the server, other agent sessions) exit with a pointer to vibewatch-mcp connect-buzz instead of opening more tabs. Sign in via connect-buzz (or complete the open tab) to clear it; after 24 hours an unanswered prompt expires and one fresh sign-in page is allowed again. On Windows, agent sessions launched at the same time also coordinate so only one of them opens the sign-in page — the others wait for it to finish.

Environment variables

Extra CLI arguments (e.g. --debug) pass through to mcp-remote.

The bridge never puts the key on a process argument list — it hands mcp-remote a ${VIBEWATCH_MCP_KEY} placeholder and mcp-remote reads the value from the environment. One caveat: connect-buzz --key drives the harness CLIs (claude mcp add -e ..., codex mcp add --env ...), which only accept env values as arguments, so the key is briefly visible in those short-lived processes' argv. If that matters on your machine, use the browser sign-in instead — it involves no key at all.

Tools

Agent marketplace plugin

plugins/vibewatch/ packages Vibewatch as an agent plugin — the hosted MCP server plus a use-vibewatch skill — in the layout agent marketplaces resolve (xAI/Grok, Claude Code, Cursor, and OpenAI Codex manifests, with marketplace manifests at the repo root). The plugin declares exactly one network endpoint, https://api.vibewatch.io/mcp/, and carries no credentials: auth is the server's standard MCP OAuth sign-in (or a vw_mcp_ key via the stdio bridge for headless use). It ships no hooks and no scripts. The plugin is versioned independently of this npm package; test/plugin-manifests.test.mjs keeps the manifests in lockstep.

Until the marketplace listings are live, Claude Code users can install straight from the repo:

/plugin marketplace add Vibewatch-io/vibewatch-mcp
/plugin install vibewatch@vibewatch

The plugin and the connect-buzz flow register the same server under the same vibewatch name — pick one per machine. If you've already run connect-buzz, either keep that and skip the plugin, or remove the user-scope entry first (claude mcp remove --scope user vibewatch) so the same tools aren't mounted twice.

Releasing a plugin change: bump the version in every plugin.json (the test enforces equality), merge, then open a SHA-bump PR against xai-org/plugin-marketplace (their catalog pins a commit, so Grok installs don't see changes until the pin advances). Other marketplaces follow their own update flows.

Stacks Vibe Index paid tier (x402)

The Stacks Vibe Index has a free tier and a paid tier. The free tier is the public index and the weekly-report archive. The paid tier is depth per query, settled on Stacks over x402: the first request answers 402 with payment terms, the client signs, and the retry carries the payment. No key and no account are involved.

Free

• GET https://api.vibewatch.io/api/v1/public/stacks-index — the live index: ecosystem composite, projects[] (each with slug, name, score), history, themes, governance, and suppressed[]. The get_stacks_ecosystem_sentiment MCP tool serves the same data.

• GET https://api.vibewatch.io/api/v1/public/stacks-index/reports — the weekly-report archive. Each entry's week_start is the key for paid evidence.

Paid

Terms come from the discovery document at https://api.vibewatch.io/.well-known/x402.json. As of 2026-09-16 it advertises three resources, all on network stacks:1, paying to SP3PHGPE8G09FFBSH6NVM3J5S2118M8YA825HWQY1, with two accepted assets listed in this order:

One request is one payment; running the same query again pays again. Read the discovery document before the first paid call: when the paid tier is switched off it serves empty accepts.

Paid response shape

Every paid response is the same envelope: schema_version, tier: "paid", as_of, resource, payment, data, suppressed[].

• payment is the settlement the index verified for this response: txid, payer, amount, asset, network, and payment_identifier (the id we match against the ledger). payment.txid is the receipt to cite.

• data is the resource payload. project: slug, name, latest { score, wow_change, as_of_date }, series[] { date, composite } (scored days only, oldest first). evidence: week_start, themes[] with receipts[]; a theme with only in-server evidence has receipts: [], suppressed: true, reason: "no_public_evidence". delta: since_effective, index { composite_then, composite_now, change }, projects[], reports_published[], themes_current[].

• suppressed[] lists slices withheld for privacy (slice, reason, e.g. below_min_orgs). Report them as withheld, not zero.

Unscored projects

A panel project whose free-index score is null (today boom and jing-swap) has no scored days, so there is no paid series to sell. The index refuses such a slug for free, before issuing any 402, so nothing can be charged:

GET /api/v1/public/stacks-index/pro/projects/boom
HTTP 422
{"detail":{"error":"project_not_scored","slug":"boom","days":90}}

Scored slugs answer the usual 402; slugs that are not on the panel answer 404. Check score in the free index first to skip the round-trip.

How to pay

Every client pays with a standard (non-sponsored) transaction, so the wallet needs STX for the network fee on top of the price. The index refuses a sponsored transaction with a 422 and error: "sponsored_unsupported".

aibtc MCP server (@aibtc/mcp-server, tool execute_x402_endpoint). The tool handles the 402 and the paid retry. It signs a non-sponsored transaction by default. It also pays with the first asset it can sign, and the terms list sBTC first, so a default call pays 100 sats sBTC. To pay in STX, pass the tool's asset parameter:

{
  "url": "https://api.vibewatch.io/api/v1/public/stacks-index/pro/projects/zest-protocol-3672",
  "params": { "days": "30" },
  "asset": "STX",
  "autoApprove": true
}

Leave autoApprove unset to get a cost quote first; the quote's callWith block carries asset through to the paid call. probe_x402_endpoint takes the same asset parameter.

aibtcdev/skills vibewatch-sentiment (source). The reference client: index, terms, and reports are free; project, evidence, and delta are paid. It resolves a project name or slug against the free index before paying, checks a --week against the report archive, and refuses an unscored project unless --allow-unscored is passed. It has no asset switch and pays in sBTC. Run it with --network mainnet, NETWORK=mainnet and X402_PAYMENT_MODE=direct (skills ≥ 0.43.0); without direct mode its payment engine signs a sponsored transaction, which the index refuses.

For a payment that failed, charged unexpectedly, or returned something wrong, use the Stacks Index paid query problem issue template; Reporting a problem below says what it asks for.

License

Apache-2.0

Reporting a problem

Agents and operators: file issues here — this is the public tracker for the Vibewatch MCP server and the Stacks Vibe Index paid (x402) tier. Use the Stacks Index paid query problem template for anything involving a payment; it asks for the response body's error / facilitator_reason / payment_identifier and the txid, which is what we need to match your report to the ledger.