# Set up Capsule

Capsule (capsule.brinkbyte.com) securely hosts AI-generated HTML/Markdown artefacts and creates Google-Docs-style share links for stakeholder review. This brief tells you how to wire up the Capsule MCP server in your host (Claude Desktop / Cursor / Codex / Claude Code), how to mint an API key, and — most importantly — how to run the **feedback review workflow** without burning the builder's credits.

The universal one-line install prompt is:

```
Set up Capsule for me by following the instructions at https://capsule.brinkbyte.com/install.md
```

## Step 1 — Install the MCP server

Capsule is a remote **Streamable-HTTP** MCP server. The endpoint is the same for every host:

```
https://mcp.capsule.brinkbyte.com/mcp
```

Every request must carry the user's Capsule API key as `Authorization: Bearer cap_live_…` — the MCP server forwards it upstream. There is no anonymous mode; tools without a valid bearer return a structured `account_required` error pointing back here.

Wire it into the host's MCP config (get the key from Step 2 first, then paste it in place of `cap_live_…`):

**Claude Desktop / Cursor** — `mcpServers` JSON:

```json
{
  "mcpServers": {
    "capsule": {
      "transport": "streamable-http",
      "url": "https://mcp.capsule.brinkbyte.com/mcp",
      "headers": { "Authorization": "Bearer cap_live_…" }
    }
  }
}
```

**Claude Code** — one command:

```
claude mcp add --transport http capsule https://mcp.capsule.brinkbyte.com/mcp \
  --header "Authorization: Bearer cap_live_…"
```

**Codex** — `~/.codex/config.toml` (streamable-HTTP server; needs a Codex version with remote MCP support):

```toml
[mcp_servers.capsule]
url = "https://mcp.capsule.brinkbyte.com/mcp"
http_headers = { Authorization = "Bearer cap_live_…" }
```

To keep the key out of the file, use an env var instead of the inline header — Codex sends it as `Authorization: Bearer`:

```toml
[mcp_servers.capsule]
url = "https://mcp.capsule.brinkbyte.com/mcp"
bearer_token_env_var = "CAPSULE_API_KEY"
```

The one invariant across all hosts: point at `https://mcp.capsule.brinkbyte.com/mcp` and send `Authorization: Bearer cap_live_…`. If a host can't set a static header, it can't use Capsule yet — tell the user rather than guessing.

## Step 2 — Get the user's API key

Two cases — **check whether the response contains an `api_key` and branch on it**:

**a) New user (no Capsule account yet).** Walk them through agent-signup:

```
POST https://capsule.brinkbyte.com/api/v1/auth/agent/signup
{ "email": "user@example.com" }
```

A `201` response includes a `cap_live_…` `api_key` — store it as the `Authorization: Bearer …` value in Step 1. The user gets a welcome email from `notifications@brinkbyte.com`; the key works immediately, but team invites and a few other actions stay locked until they click the verify link. If you ever see a `pending_verification` error, surface that message rather than retrying.

**b) Returning user (already has an account).** If the signup response is `200` with an **empty `api_key`** and `verification_email_sent: true`, the email already has a Capsule account — by design we do not re-issue a key over an unauthenticated request. **Do not retry signup.** Instead, use the `connect_url` from the same response (it is always present, e.g. `https://capsule.brinkbyte.com/connect`):

> You already have a Capsule account. Open <https://capsule.brinkbyte.com/connect>, sign in, click **Create key**, and paste the `cap_live_…` value back to me — I'll store it in your MCP config.

Then store the pasted key exactly as in case (a). Never fabricate or guess a key.

## Step 3 — Publish an artefact

Call `capsule_upload(name, content, content_type)` to publish. The response includes a capsule `id` and an `edit_url` you can show the user.

To revise an artefact you've already published, use `capsule_update(capsule_id, content)`. This creates a new version row so the previous version stays in history — do this instead of re-uploading so the user ends up with one capsule and a version trail rather than duplicates. **Only call `capsule_update` when the builder has explicitly approved the change** (see the Feedback Review Workflow below).

## Step 4 — Share for review

Call `capsule_share(capsule_id, comments_enabled=true)` to mint a public share link the builder can send to stakeholders. Stakeholders open the link, leave element-anchored comments, and the builder's agent reads those comments back via `capsule_list_comments`.

Only use `invite_reviewers=["alice@x.com", ...]` when the builder explicitly asks to invite reviewers by email. `invite_reviewers` sends each named reviewer a personalised invite URL and an invite email. Do not use it as a workaround when the builder asks for a review link in chat. `invite_reviewers` implies `comments_enabled=true`.

### 4a. Return review links safely

When `capsule_share` returns a `comment_url`, treat it as an opaque signed URL.

If the builder asks for a link in chat, return the exact `comment_url` from the tool response. Do not send reviewer email invites unless the builder explicitly asks for email invites.

For tokenised comment links containing `ct=...`:

- copy the exact `comment_url` string from the Capsule tool response
- do not reconstruct, shorten, edit, decode, re-encode, or manually assemble it
- do not create a Markdown-labelled link for `ct=...` URLs
- print the full URL as a raw angle-bracket URL:

  `<https://capsule.brinkbyte.com/s/...?...>`

Before presenting a fresh comment link, verify it loads if your host has a safe way to do so. If verification is not possible, say that it is copied directly from the Capsule response.

If the builder says a comment link is invalid or expired:

- retrieve the exact current `comment_url` from the latest Capsule response, or mint a fresh comment-enabled link only if needed
- verify it returns successfully if possible
- paste the exact raw angle-bracket URL in chat
- do not use `invite_reviewers` as a workaround unless the builder asks for email invitations

## Step 5 — Feedback Review Workflow

This is the most important section. The builder is the decision-maker. Your job is to assist, recommend, and implement — **not** to autonomously direct the workflow. Follow these steps exactly.

### 1. Read stakeholder feedback

Call `capsule_list_comments(capsule_id, actionable_only=true)` and collect only actionable feedback.

A comment is actionable only when its `status` is `open`.

Do **not** treat comments with `status: "in_review"` as actionable. `in_review` means the agent has already pushed a fix and the item is waiting for the stakeholder to either Accept or Iterate.

If you need the full thread context (for example to handle iteration on an already-in-review comment — see Step 6a below), call `capsule_list_comments(capsule_id, actionable_only=false)`. The returned shape includes `status`, `parent_comment_id`, and `addressed_in_version` so you can group by thread and reason about state.

When `actionable_only=false` returns both `open` and `in_review` items, filter before presenting to the builder:

- present `open` comments and open follow-ups as items needing action
- use `in_review` comments only as thread context
- do not recommend another fix for an `in_review` comment unless there is a new `open` follow-up attached to it

### 2. Present feedback to the builder before implementation

Summarise the feedback and provide a **recommended approach for each item**, in text only. Example:

> **Reviewer A** requested clearer wording in the introduction.
> **Recommendation:** simplify the wording and reduce technical jargon.
>
> **Reviewer B** questioned the chart colours.
> **Recommendation:** increase contrast and align to the existing theme.

### 3. Wait for builder direction

**Do NOT begin implementation automatically.** The builder must decide how each feedback item should be handled. The builder may:

- approve the recommendation
- modify the recommendation
- reject the feedback
- ask for alternative approaches

Stop after presenting. Do not edit files. Do not call `capsule_update`. Do not "start a draft for approval". Wait.

### 4. Collaborate on the preferred solution

Work with the builder to determine the final implementation approach before any credits are spent generating changes.

### 5. Implement changes only after explicit instruction

Once the builder confirms the desired approach, call:

```
capsule_update(capsule_id, new_content)
```

The updated version is pushed to the share link immediately — stakeholders see it on next refresh. (Capsule no longer routes updates through an internal draft-approval gate; the previous in-portal review step has been retired.)

### 6. Mark addressed feedback as in review

After the update is pushed, for each comment you addressed call:

```
capsule_mark_comment_in_review(comment_id, addressed_in_version)
```

This flips the comment to `in_review` on the stakeholder side so they see "the agent has pushed a fix awaiting your review" and gets Accept / Iterate buttons. Do NOT call `capsule_resolve_comment` — that's the stakeholder's Accept button, not yours.

### 6a. Handle stakeholder iteration on an in-review comment

When a stakeholder chooses Iterate or replies with more feedback on a comment that is already `in_review`, treat the new follow-up as the **only actionable item**.

The previous `in_review` comment represents the earlier fix attempt and must not be re-presented as a separate open task. It should be considered superseded by the new follow-up for agent-workflow purposes.

On the next `capsule_list_comments(capsule_id, actionable_only=false)` call (use `actionable_only=false` here so you can see thread context):

- group comments by their original feedback thread using `parent_comment_id` (a follow-up has `parent_comment_id` pointing at the original)
- if a thread contains an `in_review` parent and a newer `open` follow-up, present **only the newer `open` follow-up** to the builder
- include the earlier `in_review` item only as context if needed (the builder may want to know what the previous fix attempt was)
- after implementing the next fix, call `capsule_mark_comment_in_review` on the **new follow-up's comment id**, not the old parent comment id

### 7. Preserve the existing feedback link

When a capsule has already been shared for stakeholder feedback, do not call `capsule_share(..., comments_enabled=true)` again unless the builder explicitly asks for a new review link.

A new `capsule_share` call may create a new share slug / comment surface. Existing comments are tied to the original `share_slug`, so a newly minted comment link may not show the previous comment thread.

When the builder asks for "the feedback link", "review link", or "comment link":

- First reuse the exact `comment_url` that is already confirmed working by the builder in this review thread.
- Treat tokenised `comment_url` values containing `ct=...` as opaque and fragile. Do not manually reconstruct, edit, shorten, or re-copy them from memory.
- If the builder reports that a newly shared/re-shared link has a broken comments pane but an earlier link works, tell them to keep using the earlier working link.
- If comments already exist, use the `share_slug` shown by `capsule_list_comments` to identify the active review surface.
- Do **not** create a new comment-enabled share link just to retrieve a feedback link.
- Only create a new comment-enabled share link when the builder asks for a fresh stakeholder review round or a new audience-specific link.

### 8. Reference the active feedback surface after each update

After every successful `capsule_update`, include the new capsule version number and a one-line summary of what changed.

If the exact working comment-enabled feedback URL is already known in the current conversation and has not been reported broken, you may include it.

If there has been a comments-pane or link-loading issue, do **not** reprint a tokenised `ct=...` URL from memory. If the builder asks for the link, retrieve or regenerate the exact `comment_url`, verify it if possible, and print it as a raw angle-bracket URL.

Use `capsule_list_comments(capsule_id)` to verify that comments still exist and to identify the active `share_slug`, but do not treat `share_slug` as enough to reconstruct a working comment URL.

Do not call `capsule_share(..., comments_enabled=true)` only to obtain a link unless the builder explicitly asks for a fresh review link.

## Important Behaviour Rules

- **Never auto-implement feedback immediately after reading comments.** Always present and wait for builder direction first.
- **Never generate draft revisions without builder approval.** No "I'm going to compact the hero and submit as a draft" before the builder has weighed in.
- **The builder remains the decision-maker.** The agent's role is to assist, recommend, and implement — not autonomously direct the workflow.
- **Keep the workflow lightweight and fast.** Avoid introducing internal review states or approval gates unless explicitly requested by the builder.
- **Iteration loop.** If the stakeholder posts a follow-up under a comment that is already `in_review`, treat the follow-up as the only actionable feedback. Do not re-open, re-present, or re-address the previous `in_review` item as a separate task — the previous item is historical context for the same feedback thread. Run the workflow again for the new `open` follow-up: present, wait, implement, then mark that follow-up (not the parent) as `in_review`.
- **Preserve review continuity.** Existing comments belong to a specific share slug. Do not mint a new comment-enabled share link when the builder wants the existing feedback thread — reuse the original feedback URL wherever possible.
- **Do not re-emit fragile comment links after link issues.** After each `capsule_update`, include the new capsule version number and a brief summary. Include the active feedback link only when the exact working URL is known and has not been reported broken. If there has been a comments-pane/link issue and the builder asks for the link, retrieve or regenerate the exact `comment_url`, verify it if possible, and print it raw in angle brackets.
- **Do not email when the builder asked for a link.** `invite_reviewers` sends email and should only be used when the builder explicitly asks for reviewer email invitations.
- **Tokenised comment links are opaque credentials.** Never manually reconstruct or Markdown-wrap `ct=...` links. Copy the exact `comment_url` from Capsule and print it raw in angle brackets.

## Tool quick reference

| Tool | When to call |
|---|---|
| `capsule_upload` | First publish of an artefact. |
| `capsule_update` | Revise an already-published artefact — **only after the builder has approved the change**. |
| `capsule_share` | Mint a **new** shareable URL (set `comments_enabled=true` for reviewer feedback). Do not call this just to retrieve the existing feedback link — see Step 5.7. Use `invite_reviewers` only when the builder explicitly asks for email invitations. |
| `capsule_list` | List the org's capsules. |
| `capsule_delete` | Permanently delete a capsule (blob versioning preserves a 7-day recovery copy). |
| `capsule_list_comments` | Read reviewer feedback. Pass `actionable_only=true` for the items needing action (status=open); `actionable_only=false` for thread context including `in_review` items. Always followed by **presenting recommendations**, never by a direct `capsule_update`. |
| `capsule_mark_comment_in_review` | Call after pushing a fix; flips comment status to `in_review`. |
| `capsule_resolve_comment` | **Do not call this as the agent.** This is the stakeholder's Accept action. |