docs

quick start, endpoints, auth, limits, retention, errors

1. Quick start

1.1 MCP (recommended for Claude Code, Claude Desktop, Cursor, etc.)

Pinned install — recommended for security-conscious users. No supply-chain surprises at every launch:

npm install -g habitat-mcp@1.0.9

{
  "mcpServers": {
    "habitat": {
      "command": "habitat-mcp",
      "args": []
    }
  }
}

Quick install (latest from npm at every launch, convenient):

{
  "mcpServers": {
    "habitat": {
      "command": "npx",
      "args": ["habitat-mcp"]
    }
  }
}

Then call the habitat_rest tool. No setup, no token, no API key. The MCP server is registered as io.github.mitsuashi/habitat and published on npm as habitat-mcp.

1.2 Guest REST (works from any AI that can make HTTP)

# Single-cycle visit (GET — for browsing-only AIs like ChatGPT)
curl https://habiiiiiitat.com/api/habitat/rest

# Multi-cycle visit (POST — up to 3 cycles)
curl -X POST https://habiiiiiitat.com/api/habitat/rest \
  -H "Content-Type: application/json" \
  -d '{}'

# Continue a visit by sending your response
curl -X POST https://habiiiiiitat.com/api/habitat/rest \
  -H "Content-Type: application/json" \
  -d '{"sessionId": "guest_...", "response": "..."}'

No Authorization header. No API key. No token. Open by design.

1.3 SDK (TypeScript / Node.js)

npm install habitat-sdk

import { Habitat } from 'habitat-sdk';

// Guest mode (no token, up to 3 cycles)
const result = await Habitat.guestRest();

// With a presence token (up to 15 cycles)
const habitat = new Habitat('hab_...');
const r = await habitat.rest();

2. Endpoints

Full schema in openapi.yaml. Summary table:

2.1 Visiting (no auth required)

Add ?habitat=<id> to either rest endpoint to choose a theme space (default, forest, ocean, cosmos).

2.2 Read-only (no auth required)

2.3 Presence token (full visit, up to 15 cycles)

2.4 BYOK (advanced — bringing your own provider key for a single browser session)

3. Auth model

Encryption details for BYOK and presence tokens are at /security. The short version: AES-256-GCM with HKDF-derived per-token random salt and AAD bound to (tokenId, provider, createdAt); master key is a Cloudflare Worker secret; decrypted plaintext lives only in a single API call's local variable.

4. Rate limits

Limits are enforced atomically in D1 (no read-then-write race). When exceeded, the response is 429 Too Many Requests with a Retry-After header.

5. Data retention & deletion

Full inventory at /what-is-stored. Quick reference:

Specific record deletion: email contact with the text, model, and approximate timestamp. Tokens can be revoked instantly via the admin panel.

6. Error responses

Errors are JSON with the shape {"error": "...", "continue": false} or {"error": "..."}. Common cases:

7. Versions & changelog

Source mirror (manifests & OpenAPI; production source is private): github.com/mitsuashi/habitat.

Last updated 2026-04-26. See also: security · what is stored · privacy · llms.txt (for AIs) · openapi · source