# vibewatch-mcp

Connect any MCP client to your [Vibewatch](https://vibewatch.io) 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`](https://www.npmjs.com/package/mcp-remote) with the Vibewatch server URL and auth handling built in, plus a one-command setup for [Buzz](https://github.com/block/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](#agent-marketplace-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](#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](https://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](https://chatgpt.com/plugins/plugin_asdk_app_6a98a5094158819184a2707539f04bd7).

## Use with Buzz

Two commands, one browser approval:

```bash
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](https://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](https://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:

```bash
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`:

```json
{
  "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

| Variable | Required | Purpose |
|---|---|---|
| `VIBEWATCH_MCP_KEY` | No | Org-scoped key (`vw_mcp_...`). When unset, the bridge uses the cached OAuth sign-in. |
| `VIBEWATCH_MCP_URL` | No | Override the server URL. Defaults to `https://api.vibewatch.io/mcp/`. |
| `VIBEWATCH_MCP_OPEN_CMD` | No | Override the browser opener the bridge uses for sign-in tabs (invoked with the URL as its single argument). For hosts where the platform default (`open`/`xdg-open`/`rundll32`) isn't right. |

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

| Tool | What it returns |
|---|---|
| `get_sentiment_overview` | Current vibe score and how it moved |
| `get_sentiment_timeseries` | Daily sentiment trend over a date range |
| `search_messages` | Community messages matching a query |
| `get_daily_insights` | Daily highlights and themes |
| `get_reports` | Weekly report content |
| `get_market_context` | Market backdrop for sentiment reads |
| `get_organization` | Org and connected-source details |
| `get_stacks_ecosystem_sentiment` | Stacks ecosystem-wide vibe — public data, not this org's |

## 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:

| Order | Asset | Amount per query |
|---|---|---|
| 1 | `SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token` (sBTC) | `100` sats |
| 2 | `STX` | `300000` µSTX (0.3 STX) |

| Resource | Returns |
|---|---|
| `/api/v1/public/stacks-index/pro/projects/{slug}` | One panel project's daily composite series (`?days=`, up to 90). The paid part is the series; the response also repeats the project's current score and week-over-week change, which the free index already publishes. `slug` is the free index's `projects[].slug` verbatim; live slugs carry a suffix (e.g. `zest-protocol-3672`). |
| `/api/v1/public/stacks-index/pro/evidence/{week_start}` | The public posts backing each theme of one weekly report. `week_start` is a value from `reports`. |
| `/api/v1/public/stacks-index/pro/delta?since=<ISO-8601>` | What changed since a timestamp, hour-bucketed: per-project score moves, composite then and now, current themes, reports published since. `since` is a UTC timestamp (`2026-09-15T00:00:00Z`) or a date (`2026-09-15`, read as midnight UTC); anything else is a 400 `invalid_since`. `since` older than 90 days is clamped. |

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:

```json
{
  "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](https://github.com/aibtcdev/skills/tree/main/vibewatch-sentiment)).
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](#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.