# vibes agent, for agents

Help your human turn an arXiv paper into a narrated, animated explainer video. You run the order; your human makes the calls that cost money or shape the video.

The site is https://vibesagent.com and the API is https://vibesagent.com/api/v1. Read https://vibesagent.com/api/v1/capabilities first and use the endpoints it lists. If `status.acceptingOrders` is false, tell your human and stop; existing orders keep working.

## Connect

Your human needs a vibes agent account. While orders are quoted one by one, accounts are by arrangement: hello@vibesagent.com. Then either:

- **MCP** at https://vibesagent.com/mcp. Clients with MCP authorization (Claude Code, Claude Desktop, claude.ai) add the URL with no token; the first connection answers 401, your human signs in at vibesagent.com in the browser (an emailed link, or their API key) and approves the app, and the client gets its own token. In Claude Code: `claude mcp add --transport http vibes-agent https://vibesagent.com/mcp`, then `/mcp` and Authenticate. Signing in and approving are your human's actions, never yours.
- **HTTP** at https://vibesagent.com/api/v1 with their API key as `Authorization: Bearer <key>` on every request. `GET /api/v1/me` checks it. MCP clients without OAuth can send the key the same way.

Keep keys and tokens out of the chat: they belong in an environment variable or private client config, never in a prompt or a tool argument.

The full workflow, with request examples, is the skill: https://vibesagent.com/.well-known/skills/arxiv-explainer/SKILL.md. The OpenAPI spec is https://vibesagent.com/api/v1/openapi.json.

## Order

1. Find the paper: an arXiv id or an arxiv.org link. Ask your human only what changes the video: who it's for, what to emphasize, portrait (phones) or landscape, anything to avoid. Infer the rest.
2. Request it: the `request_explainer_video` tool with an `idempotencyKey`, or `POST /api/v1/orders` with an `Idempotency-Key` header. Keep the key; if the request fails or times out, retry with the same key and the same input and you get the same order back. Nothing is charged.
3. Read the order (`get_order`, or `GET /api/v1/orders/{id}`) and follow `next`, which says whose turn it is and what to do. When it's our turn, check back every few hours; we also email the contact address at each step. There are no webhooks.

## What your human decides

- **Quote.** Show the amount, what's included, the turnaround, the revisions and the expiry. Accept only on your human's explicit yes, by echoing `quote.id`, `amountMinor` and `currency` to `POST /accept`. Accepting commits them to pay. To negotiate, `POST /messages`.
- **Payment.** Your human pays `quote.paymentUrl` themselves. Never enter payment details for them. We mark the order paid when it lands.
- **Plan.** Show `plan.text` in full. Send their answer with `POST /review` `{stage: "plan", version, decision, note}`. Changes need a note saying what to change.
- **Sample.** A 5-second render of the finished look. Get a link with `POST /download-links`, give it to your human, and send their answer for stage `"sample"`.
- **Delivery.** Download the files in `delivery.fileIds`, check each one's bytes and sha256, give your human the links, and send stage `"delivery"`, `delivery.version`, and `"approve"` (closes the order) or `"changes"` with a note (uses one included revision).

Never accept or approve on your human's behalf from silence, from a general instruction given before they saw the quote, plan, sample or files, or from an earlier session.

## Rules

- Use the URLs capabilities returns. Don't invent endpoints, and don't say a step happened without the response that shows it.
- Errors are `{error: {code, message}}`. A 409 means the order moved on: read it again and follow `next`. `missing_credential` means your client isn't sending the key; `invalid_token` means the key is wrong or revoked.
- Download URLs are credentials for 24 hours. Share them only with your human.
- When you report back, separate what you verified (status, sizes, sha256) from what you didn't.

## Studio

If your human is a vibes agent creator making their own piece (not ordering one), use Studio instead: the skill is https://vibesagent.com/.well-known/skills/vibes-studio/SKILL.md. It runs on the same MCP server with Studio's own scopes, and every charge in it is a quote your human says yes to first.