hdls.ai — Customer Documentation
Your SaaS backend, run from your AI assistant. No dashboard to learn, no API keys to paste. Connect once, then just tell Claude, Cursor, or Codex what you want — and it calls the right tool.
What hdls is
hdls is a portfolio of headless, MCP-native SaaS backends — the database is the product. Instead of logging into a web app and clicking around, you operate 37 production backends (CRM, Support, Billing, Inventory, HR, and more) from your AI assistant by calling named tools over the Model Context Protocol. The data is the deliverable; there's no per-product UI to learn.
You connect in two layers:
| Layer | Endpoint | What it's for |
|---|---|---|
| Concierge (control plane) | https://hdls.ai/api/mcp | Discover products, install what you need, invite teammates, find skills, store workspace memory |
| Product (the work) | https://hdls.ai/api/mcp/<slug> | One product's named record tools, e.g. /api/mcp/crm → create_account, search_accounts, summarize_account |
Authentication is one-click OAuth 2.1 — nothing to copy. Tenant isolation is
automatic: your credential is pinned to one workspace, enforced by Postgres
row-level security, so you never pass a tenant_id.
Who it's for: founders, ops and revenue teams, and builders who'd rather operate their tools through an AI assistant than maintain another web app — and who want their data to stay theirs, isolated by the database itself.
5-minute quickstart
Five steps from zero to a real record. The example uses Claude Code's CLI; any MCP-capable assistant follows the same shape.
1. Connect the concierge and sign in (one-click OAuth)
claude mcp add --transport http hdls https://hdls.ai/api/mcp -s user
Then trigger the OAuth flow inside Claude:
/mcp
Your browser opens to hdls. Sign in (passwordless), pick your workspace and the
products this connection may touch on the consent screen, and click Allow
access. No key is ever pasted. (Config-file clients: add {"mcpServers":{"hdls": {"url":"https://hdls.ai/api/mcp"}}} and authorize the prompt.)
2. See what exists
Tool: list_products
Arguments: {}
Returns every product with its one-line description, the named tools it exposes,
its dedicated endpoint, and an installed flag for your workspace — your whole
capability map in one call.
3. Install the product you need (admin/owner)
Tool: install_product
Arguments: { "slug": "crm" }
Idempotent and instant — it records that your workspace uses the CRM and lights up
its tools at /api/mcp/crm. (A brand-new workspace ships with crm already
available, so your first connection is never empty.)
4. Connect to the product endpoint
Add the product as its own connector — same OAuth, one click:
claude mcp add --transport http hdls-crm https://hdls.ai/api/mcp/crm -s user
/mcp
5. Do one real thing
Tool: create_account
Arguments: { "name": "Acme Corp", "domain": "acme.com", "industry": "Manufacturing" }
That's it — you created a record without ever naming a tenant or owner; they're
stamped server-side. From here, search_accounts, create_deal, log_activity,
and summarize_account all work the same way.
💬 Just ask: Once you're connected, you don't have to name tools or arguments yourself. Say "set up a CRM and add Acme Corp as an account" and your assistant installs the product, connects to its endpoint, and calls
create_accountfor you.
One thing to remember: installing a product does not put its tools on the concierge. They live on the product's own endpoint (
/api/mcp/<slug>) — add that connector to call them.
Table of contents
Read these in order for a guided path, or jump to what you need.
| Page | What it covers |
|---|---|
| What hdls is & how it works | Start here. The one mental model: the database is the product, concierge vs. product endpoints, workspace = tenant, automatic RLS isolation, roles, and a first-five-minutes walkthrough. |
| Connect your AI assistant | Step-by-step connection for Claude, Cursor, Codex, and any MCP client — adding the concierge, completing OAuth consent, adding per-product connectors, and minting scoped API keys for headless use. |
| Using hdls day to day | How to actually operate hdls from your assistant — discovering tools, the install-then-connect rhythm, and what to say to get work done. |
| Products, tools & custom fields | The full catalog of 37 products, how to discover and install them, a worked CRM example with every named tool, and tailoring records with custom fields (plus the generic-engine fallback). |
| Hosted pages: reports, dashboards & forms | Publish a real hosted page with publish_page — sandboxed documents, live dashboards that re-aggregate on every view, and public intake forms that write straight back into a product. |
| Triggers, schedules & waking agents | Automate with create_trigger — fire on database events or a schedule, gate with conditions (including now.* time fields), run task/webhook/agent/email targets, and the wake-agent pattern. |
| Skill playbooks | Pull in ready-made skill playbooks — search and apply proven, product-specific workflows so your assistant does the right thing the first time. |
| Teams & roles | Invite teammates through the human-confirmed flow and the four-role model (reader < member < admin < owner). |
| Workspace memory | Keep shared and personal workspace memory across sessions, so your assistant remembers context between conversations. |
| Security, isolation & trust | Plain-language trust page: Postgres RLS isolation, OAuth 2.1 + PKCE with rotating tokens, signed webhooks, BYO-DB SSRF protection, encrypted secrets, rate limits — each with a way to verify it yourself. |
Core concepts
A short glossary — learn these six and everything else follows.
- Workspace (tenant) — Your isolated world of data. One workspace is one tenant; your credential is pinned to it, and isolation is enforced by the database, not by application code. You never pass a tenant id.
- Concierge — The control-plane endpoint at
https://hdls.ai/api/mcp. It tells you what exists and lets you manage the workspace (discover/install products, invite teammates, find skills, store memory, publish pages). It does not do day-to-day record work. - Product endpoint — A single product's own endpoint at
https://hdls.ai/api/mcp/<slug>(e.g./api/mcp/crm). This is where you do the work, calling that product's named, self-describing tools. - MCP (Model Context Protocol) — The open standard your AI assistant speaks to call hdls tools. Any MCP-capable client (Claude, Cursor, Codex, your own agent) connects the same way.
- RLS (Row-Level Security) — The Postgres feature that pins every row to its workspace. A query with no workspace context returns zero rows — it fails closed, so cross-tenant access isn't a failure mode that exists here.
- Trigger — Stored "if this, then that" automation: when a database event or schedule fires and your conditions hold, hdls runs a target (queue a task, POST a signed webhook, wake an agent, or send an email) — no servers to babysit.
Roles run
reader < member < admin < owner. Reading is open to everyone; writing records needsmember; installing products and inviting teammates needadmin; uninstalling needsowner.
Where to go next
- New here? Read What hdls is & how it works first.
- Ready to connect? Follow Connect your AI assistant.
- Connected and want to get things done? See Using hdls day to day.
- Already connected? Ask the concierge
helpfor your live connection status, orsearch_docsto search this documentation from inside your assistant.
- Power tools — the generic engineThe low-level do-anything layer at /api/mcp beneath the named product tools — discover tables, query and analyse records, write rows, and link records across products.
- Products & toolsThe hdls catalog — 37 headless SaaS backends with purpose-built named tools. Discover with list_products, install with install_product, then connect and tailor with custom fields.
- Quick start: zero to a live dashboardConnect your assistant, turn on a product, and open a live dashboard in about five minutes — all by talking to your AI. The exact tool calls are shown so you can see what happens under the hood.
- Skills — reusable playbooksPull battle-tested playbooks into your assistant with search_skills and get_skill — ~45 curated skills from a global, read-only registry, applied with no install step.
- Bring your own databasePoint hdls at your own existing Postgres instead of the managed database — how linking works, the SSRF and DNS-rebind guardrails that keep it safe, and minting a scoped key.
- Teams & rolesInvite teammates with invite_teammate — a propose-then-confirm flow where a human owner/admin approves the share before it sends — and the reader/member/admin/owner role model.
- Using hdls — just talk to your assistantThe friendly, no-code start. hdls is your back-office — CRM, helpdesk, and more — that you run by talking to your AI assistant. Connect once, then just ask.
- Customer portalsLet your own customers interact with your hdls backend — e.g. raise and track their own support tickets — with per-principal isolation so customer A never sees customer B.
- What hdls is & how it worksThe one mental model you need — headless, MCP-native SaaS backends where the database is the product, operated from your AI assistant.
- Workspace memoryGive your assistant a memory across sessions — a team-wide workspace profile plus private per-user bio and preferences, via set/get_workspace, set/get_bio, and set_preference/get_preferences.
- Billing & plansHow hdls plans, quotas, and metered billing work — per-minute rate limits, a monthly tool-call budget, and usage-based metering.
- Connect your AI assistantConnect Claude, Cursor, Codex, or your own agent to hdls with one-click OAuth — concierge first, then each product endpoint. No keys, no SDK.
- Hosted pages: reports, dashboards & formsAsk your AI to publish_page and hdls hosts reports, live dashboards, and intake forms at stable URLs — no front-end to build, no server to run.
- Triggers, schedules & waking agentsMake your data act on its own — fire triggers on database events or schedules to enqueue tasks, post webhooks, wake agents, or send email.
- Reviewer guide — evaluate hdls end to endA step-by-step setup path for directory and security reviewers — sign up free, connect over OAuth, install the CRM, seed sample data, and walk the representative tool calls.
- Security, isolation & trustHow hdls keeps your data yours — Postgres row-level tenant isolation, one-click OAuth, pinned short-lived tokens, signed webhooks, encryption at rest.