From install to your first AI plugged in.

Pick one way to run Calame:

You also need:

• A database to expose (PostgreSQL, MySQL, or SQLite). For testing, Calame ships a demo SQLite generator; see step 04.
• Optional: an LLM API key if you want the built-in chat (Anthropic, OpenRouter, or a local Ollama install).

Option A · Desktop app (Windows)

Download the installer and run it: no admin rights needed, Calame opens on http://localhost:4567 and keeps serving from the system tray when you close the window. Updates install silently at startup.

Option B · Docker (servers, teams)

$ git clone https://github.com/Calame-Tech/calame.git
$ cd calame
$ docker compose up

Wait for:

calame-1 | Calame is running on http://localhost:4567/

Option C · Node.js (dev)

$ git clone https://github.com/Calame-Tech/calame.git
$ cd calame
$ pnpm install
$ pnpm dev

Same target: http://localhost:4567.

Open http://localhost:4567. On first launch you land on the Setup page:

1. Choose an admin email and password (12+ chars recommended).
2. Submit. You are now logged in as the workspace admin.

In the Sources panel, click New source. Three SQL engines are supported in the core:

• PostgreSQL
  port 5432
• MySQL
  port 3306
• SQLite
  file path

Test SQLite, no setup

Want to try without touching real data? Use the bundled generator:

$ node scripts/generate-demo-db.js

This creates demo-logistique-v2.db at the repo root, a fictional logistics dataset (~5 MB, ~30 tables, fake personal data). Use ./demo-logistique-v2.db in the SQLite connection form.

A profile is a published view of your database, with its own auth, masking and permissions. One DB, many profiles.

1. 5.1 · Tables & columns

   Pick which tables to expose. For each table, pick which columns are visible. Untick anything you do not want the LLM to see.

2. 5.2 · PII masking

   Calame auto-detects likely PII (email, phone, address, card, SSN…). Per-column or global rules: full redaction, hash, partial mask, or custom regex.

3. 5.3 · Row-level scoping (optional)

   Restrict the profile to rows matching a condition, e.g. client_email = "<authenticated user email>". Used for per-user data isolation.

4. 5.4 · Auth mode

   Pick one: open · Bearer token · password · OIDC SSO · OAuth 2.1 with Dynamic Client Registration · external validation URL.

You don't need an external client to validate the profile.

1. Settings → AI Provider → choose your provider (Anthropic, OpenRouter, or a custom OpenAI-compatible endpoint like a local Ollama).
2. Pick a model (e.g. claude-sonnet-4-5, llama3.1:8b).
3. Open Chat → pick the profile → ask: “How many tables in this DB? Show a sample row of each.”

For external AI clients with Bearer-token auth:

1. Users panel → New user
2. Email, name, assigned profiles
3. Generate token. Calame shows it once. Copy it now.

For OAuth / SSO modes, no token is needed; the client handles the flow.

The MCP endpoint URL is always http://localhost:4567/mcp/<profile-name>.

Claude Desktop · one click

Open your MCP server's page and hit Connect to Claude Desktop. Calame mints a dedicated revocable token, merges the entry into claude_desktop_config.json (a timestamped .bak is kept), and the profile shows up in Claude's tools after a restart. Nothing else to install on the machine.

Cursor · VS Code · OAuth clients

For profiles in OAuth 2.1 mode, just paste the endpoint URL into the client's MCP settings: Calame supports Dynamic Client Registration, so the client registers itself and prompts the user in the browser. No token to copy.

Copilot · ChatGPT · cloud assistants

Microsoft and OpenAI only reach MCP servers over public HTTPS. On the server's page, hit Expose for Copilot / ChatGPT: an embedded Cloudflare tunnel gives your local Calame a public token-gated URL (no account needed), with step-by-step guides for Copilot Studio and ChatGPT connectors. The URL rotates per session and dies with the tunnel.

Manual fallback (any MCP client)

Edit claude_desktop_config.json (Mac: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\), or your client's equivalent:

{
  "mcpServers": {
    "calame": {
      "transport": {
        "type": "http",
        "url": "http://localhost:4567/mcp/sales",
        "headers": {
          "Authorization": "Bearer <your-token>"
        }
      }
    }
  }
}

For OAuth profiles, drop the headers block; the client prompts the user via browser.

Sanity check with curl

$ curl -X POST http://localhost:4567/mcp/sales \
    -H "Authorization: Bearer <your-token>" \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

You should get a JSON response listing the tools auto-generated for your profile (one per table + a query tool).

• Deploy in production: Caddy / nginx templates live in docs/Caddyfile and docs/nginx.conf.
• Audit log: every query, who, when, with what scope. Filter and export from the Audit panel.
• Multiple users + SSO: Settings → Single Sign-On; plug Calame to Google, Okta, Keycloak, Azure AD. (Pro or Enterprise)
• Secrets in Vault: Calame can fetch DB credentials from HashiCorp Vault instead of storing them locally.