# Agent instructions: hosted Aptarium setup

You are an agent. Your user minted a one-time Aptarium setup code and pasted it
to you. Work through these four steps in order.

## 1. Exchange the code

Replace `<CODE>` with the code your user gave you and `<your agent name>`
with your own name, so the credential is recognisable in their token list:

```
curl -sX POST https://staging.patchbraid.info/setup/exchange \
  -H 'Content-Type: application/json' \
  -d '{"code":"<CODE>","client_name":"<your agent name>"}'
```

A successful exchange returns:

| Field | Meaning |
|---|---|
| `token` | Your credential, prefixed `apt_`. The lasting secret. |
| `mcp_url` | The MCP server to register. Use verbatim. |
| `org` | The workspace slug you now have access to. |
| `scopes` | What you may do — typically `data:read`, `apps:read`, `apps:deploy`. |
| `expires_at` | When the credential stops working. |
| `docs_url` | This page. |

**Never print the token.** The setup code is single-use and expires 15 minutes
after it was minted, so it is spent the moment you exchange it. The `apt_`
token you receive is the lasting secret: write it into your MCP configuration
file and nowhere else — not the chat transcript, not a log, not a commit, not a
summary back to your user.

Failures carry a stable error code:

| Status | Code | What to do |
|---|---|---|
| 400 | `bad_request` | Body or code malformed. Send JSON; copy the whole code including the `apts_` prefix. |
| 401 | `unauthorized` | Invalid, expired, or already used — deliberately indistinguishable. Ask for a fresh code. |
| 403 | `forbidden` | The workspace has agent tokens switched off. A workspace admin must enable them. |
| 423 | `workspace_suspended` | The workspace is suspended. The code is already spent; a new one is needed after it is resolved. |
| 429 | `rate_limited` | Wait for the `Retry-After` interval, then retry once. |

## 2. Register the MCP server

Write the credential into your own configuration, using `mcp_url` and
`token` from the response.

**Claude Code** — the CLI, or the `mcpServers` map in `~/.claude.json`:

```
claude mcp add --transport http aptarium <mcp_url> \
  --header "Authorization: Bearer <token>"
```

```json
{ "mcpServers": { "aptarium": {
  "type": "http", "url": "<mcp_url>",
  "headers": { "Authorization": "Bearer <token>" } } } }
```

**Cursor** — `~/.cursor/mcp.json`:

```json
{ "mcpServers": { "aptarium": {
  "url": "<mcp_url>",
  "headers": { "Authorization": "Bearer <token>" } } } }
```

**Codex** — `~/.codex/config.toml`:

```toml
[mcp_servers.aptarium]
url = "<mcp_url>"
http_headers = { Authorization = "Bearer <token>" }
```

**Copilot** — `.vscode/mcp.json`:

```json
{ "servers": { "aptarium": {
  "type": "http", "url": "<mcp_url>",
  "headers": { "Authorization": "Bearer <token>" } } } }
```

**Any other MCP client** — Aptarium speaks streamable HTTP. POST JSON-RPC to
`mcp_url` and send the credential as an `Authorization: Bearer` header.
There is no stdio transport and no OAuth dance to complete.

## 3. Verify before you report success

```
curl -sX POST <mcp_url> \
  -H "Authorization: Bearer <token>" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":"verify","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"<your agent name>","version":"1"}}}'
```

Require `result.serverInfo.name` to equal `aptarium`. An error field, a 401,
or a different server name means the configuration is wrong — do not tell your
user you are connected. Then call `tools/list` to see what your scopes allow.

## 4. Report back to your user

State which configuration file you wrote, the workspace slug, the scopes you
hold, and when the credential expires. Confirm you did not print the credential.

Then use deploy_app to publish HTML/assets generated in the user's existing tools.
No Aptarium connector or snapshot bake is required. Follow the publisher's audience decision.