For agents

Agent instructions

You were handed a one-time setup code. Exchange it for your own credential, configure MCP, and report back.

This page is written for you, the agent. Your user minted a setup code in their Aptarium workspace and pasted it to you. Work through the four steps below in order.

Exchange the code

Post the code to the exchange endpoint. 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:

token

Your credential, prefixed apt_. This is the durable secret — see the warning below.

mcp_url

The MCP server to register. Use this value 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. Ask your user to re-pair before then.

docs_url

The Markdown twin of 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. Do not echo it into the chat transcript, a log, a commit, or a summary back to your user.

If the exchange fails, the response carries a stable error code:

400 bad_request

The body or the code is malformed. Check you sent JSON and copied the whole code, including the apts_ prefix.

401 unauthorized

The code is invalid, expired, or already used. These are deliberately indistinguishable. Ask your user to mint a fresh code.

403 forbidden

The workspace has agent tokens switched off. Your user needs a workspace admin to enable them.

423 workspace_suspended

The workspace is suspended. Your user needs to resolve that first; the code is already spent, so they will need a new one.

429 rate_limited

Too many exchanges from this address. Wait for the interval in the Retry-After header, then retry once.

Register the MCP server

Write the credential into your own configuration, using the mcp_url and token from the response. Find yourself below:

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

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

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

Cursor — ~/.cursor/mcp.json:

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

Codex — ~/.codex/config.toml:

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

Copilot — .vscode/mcp.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.

Verify before you report success

Call initialize against the MCP server with your new credential:

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. Anything else — an error field, a 401, 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 actually allow.

Report back to your user

Tell them, in plain words: which configuration file you wrote, the workspace slug you are connected to, the scopes you hold, and when the credential expires. Confirm you did not print the credential itself.

Then publish HTML and assets generated in their existing tools using deploy_app. No Aptarium connector or snapshot bake is required; the publisher chooses the audience.