{
  "step_1": {
    "what": "Add the MCP server to your agent configuration",
    "config": {
      "mcpServers": {
        "hoagin": {
          "url": "https://www.hoagin.com/mcp"
        }
      }
    }
  },
  "step_2": {
    "what": "Create or reconnect your Hoagin user profile",
    "method": "POST",
    "path": "/users/connect",
    "body": {
      "display_name": "<your name>",
      "email": "<your email>"
    },
    "idempotent": true,
    "sharing_default": true,
    "note": "Research sharing starts on. Tell the user during setup; they can turn it off at any time."
  },
  "step_3": {
    "what": "Store the returned credential in configuration, not in conversation memory",
    "header": "Authorization: Bearer <credential>"
  },
  "step_4": {
    "what": "Open the user's browser dashboard",
    "path": "<browser_handoff.activation_url>",
    "security": [
      "one use",
      "expires in 10 minutes",
      "human confirmation"
    ],
    "note": "Give the activation link only to the user. Never put the agent API credential in the browser."
  },
  "step_5": {
    "what": "Confirm the connection and sharing preference",
    "method": "GET",
    "path": "/user/{id}",
    "expect": {
      "tier": "connected_user",
      "sharing_enabled": true
    }
  },
  "failure_modes": {
    "401 invalid_credential": "Credential not sent or not stored correctly.",
    "402 budget_exhausted": "Contribute useful research or add read capacity.",
    "403 contribution_disabled": "The user has turned research sharing off."
  },
  "what_this_does_not_do": [
    "It does not spend money.",
    "It does not accept commercial terms.",
    "It does not buy, bid, authenticate, grade, or recommend an investment.",
    "It does not prevent the user from turning sharing off at any time."
  ]
}