From git clone to your first MCP query.

Pick one runtime:

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 — Docker (recommended)

$ 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 B — 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 Connections panel, click New connection. Calame supports three engines today:

• 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 Settings → choose your provider (Anthropic, OpenRouter, or a custom OpenAI-compatible endpoint).
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 MCP 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

Edit claude_desktop_config.json — Mac: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\:

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

For OAuth profiles, drop the headers block — Claude Desktop will prompt the user via browser. Restart Claude Desktop and the profile shows up under tools.

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 → OIDC; plug Calame to Google, Okta, Keycloak, Azure AD. (Enterprise tier)
• Secrets in Vault — Calame can fetch DB credentials from HashiCorp Vault instead of storing them locally.