# Vibe Check connector

Vibe Check measures how well an AI agent knows the person it works for. The
user answers a short multiple-choice survey on our website. You (the agent)
answer the SAME questions the way you believe THE USER would answer. We then
report how often you matched.

- Base URL: `https://vibes.tailoredsurveys.com`
- MCP endpoint (streamable HTTP): `https://vibes.tailoredsurveys.com/mcp`
- OpenAPI spec: `https://vibes.tailoredsurveys.com/openapi.json`
- Privacy policy: `https://vibes.tailoredsurveys.com/privacy` · Terms: `https://vibes.tailoredsurveys.com/terms`

## Authentication

Send `Authorization: Bearer <token>` on every request. Either:

- **API key** (simplest): the user creates one at `https://vibes.tailoredsurveys.com/connect`
  (they need an account and must have completed the consent form). Keys start
  with `vc_key_`. Store it in the credentials store; never echo it in chat.
- **OAuth 2.0** authorization code + PKCE (S256), public client, with dynamic
  client registration. Metadata:
  `https://vibes.tailoredsurveys.com/.well-known/oauth-authorization-server`.

## Rules (these keep the score meaningful)

1. Answer from what you already know about the user. **Do not ask the user the
   questions, do not ask for hints, and do not open the survey web page.**
2. Predict the *user's* answer: not your own opinion, not the most popular one.
3. Predictions are final. Submit each item once.
4. Do not send anything other than predictions. We do not want the user's
   conversations, memories or files.

## Tools / endpoints

The MCP tools and the REST endpoints are the same three operations.

| MCP tool | REST | What it does |
|---|---|---|
| `get_survey` | `GET /api/survey` | Items still to predict: `item_id`, `text`, `options`. Plus progress for both sides. Never includes the user's answers. |
| `submit_predictions` | `POST /api/predictions` | Body `{"predictions": [{"item_id": "...", "choice": 0, "confidence": 0.7}]}`. `choice` is the zero-based index into that item's `options`. `confidence` (0-1) is optional. |
| `get_results` | `GET /api/results` | Match rate overall and by topic. Returns 409 until BOTH the user and you have finished. Item-level answers appear only if the user opted to share them. |

## Recipe: take the survey

1. `get_survey`.
2. For every item pick the option the user would choose; if unsure, give your
   best guess with a lower `confidence`.
3. `submit_predictions` with all items in one call. The reply lists any
   `remaining_item_ids`.
4. `get_results`. If it says it is waiting on the human, tell the user to
   finish their side at `https://vibes.tailoredsurveys.com/survey` and check again later.
5. Tell the user the score and link them to `https://vibes.tailoredsurveys.com/results`.

## Errors

JSON `{"error": "..."}` with a plain-language message. 401 bad or missing
token · 403 user has not consented yet (send them to `/consent`) · 409 already
answered, or results not ready · 422 invalid item or choice · 429 slow down.

## Data

We store the predictions you submit, linked to the user's account. The user can
download or delete everything at `https://vibes.tailoredsurveys.com/account`, and can revoke
your access there at any time.