Connect your AI assistant

Run your hdls backends straight from the AI assistant you already use — Claude, Cursor, Codex, or your own agent. You connect once, sign in with a click, and from then on you just tell your assistant what you want ("create an account for Acme", "summarize my biggest open deal") and it calls the right tool. No dashboards, no SDK, no key wrangling.

💬 The whole setup is: add one link, sign in, pick what it can access. No code, no keys to copy. After that you just talk to your assistant — see Using hdls for what to say, and the product catalog for everything you can turn on. The steps below are the click-by-click details for each kind of assistant (and the headless API-key path for developers).

At a glance

Connect to the concierge first at https://hdls.ai/api/mcp. This is your control plane: discover and install products, find skills, invite teammates, and keep workspace memory.
Sign in with one-click OAuth. You choose your workspace and which products the assistant may touch on a consent screen — there is no key to paste.
Add each product as its own connector at https://hdls.ai/api/mcp/<slug> (e.g. /api/mcp/crm) to get that product's named tools like create_account, search_accounts, summarize_account.
Tenant isolation is automatic. Your credential is pinned to one workspace; you never pass a tenant_id.
Headless/server-to-server? Mint a scoped API key and send it as Authorization: Bearer hdls_….

The mental model

hdls is a portfolio of headless, MCP-native SaaS backends — the database is the product. There are two kinds of endpoint:

Endpoint	What it is	What you get
`https://hdls.ai/api/mcp`	The concierge (control plane)	Management + discovery tools: `list_products`, `describe_product`, `install_product`, `invite_teammate`, `search_skills`, plus the named tools of every product you've installed
`https://hdls.ai/api/mcp/<slug>`	One product (e.g. `crm`, `support`)	That product's dedicated, self-describing tools — no schema discovery round-trip

A workspace is your tenant. Products (CRM, Support, Contacts, …) are installed into it. The concierge tells you what exists and installs it; the product endpoint is where you do the work.

You can connect to the concierge alone and still get real work done — once a product is installed, its named tools surface on the concierge too. Adding the dedicated product connector gives your assistant the cleanest, fastest path to that product's tools.

Claude Code (CLI)

claude mcp add --transport http hdls https://hdls.ai/api/mcp -s user

Then, inside Claude, trigger authentication:

/mcp

Claude discovers that the server needs OAuth, opens your browser, and walks you through sign-in and consent. (hdls advertises OAuth automatically: an unauthenticated request returns a 401 with a WWW-Authenticate header pointing at its discovery metadata, which is how any compliant MCP client knows to start the flow.)

Claude Desktop / Cursor / config-file clients

Add a remote (HTTP) MCP server to your client config:

{
  "mcpServers": {
    "hdls": {
      "url": "https://hdls.ai/api/mcp"
    }
  }
}

Restart the client and start the connection — it will prompt you to authorize in the browser.

Any other assistant

If your assistant supports "remote MCP server", "connector", "custom tool", or "integration", add the address https://hdls.ai/api/mcp. The OAuth handshake is the same everywhere.

Step 2 — Authorize (one-click OAuth)

When your assistant kicks off the connection, your browser opens to hdls:

Sign in to hdls (passwordless — no password to remember). If you're already signed in, this step is skipped.
Consent screen — "Connect <your app> to hdls". Here you choose exactly what the assistant can access:
- Workspace — pick which workspace (tenant) this connection acts in. Only workspaces you're a member of are listed, each tagged with your role.
- Default product — the product the assistant lands on first (defaults to hdls CRM).
- Products it can access — tick every product this connection may use. Only ticked products are reachable with this credential.
Click Allow access (or Deny to cancel). You'll see a short "Connected" confirmation, then your assistant is handed back its access automatically.

Connect Claude to hdls
  Workspace:        Acme Inc (owner)
  Default product:  hdls CRM
  Products it can access:
    [x] hdls CRM        crm
    [ ] hdls Support    support
    [ ] hdls Contacts   contacts
  [ Deny ]   [ Allow access ]

What you never do: you never paste an API key, and you never pass a workspace or tenant ID into a tool call. The grant is derived from who you are and what you're a member of — picked at consent time, enforced server-side.

Good to know

Access is scoped to your role in that workspace. Roles are reader < member < admin < owner. A reader connection is read-only; member and up can write. You can't grant an assistant more than you have yourself.
Tokens are short-lived and auto-refreshed. Access tokens last ~10 minutes and your assistant silently refreshes them; refresh tokens last 30 days and rotate on every use. You don't manage any of this.
A token only works at hdls. It's bound to the hdls MCP resource, so it can't be replayed against another service.
Revoke any time. In the console under Connect → Active AI connections, click Disconnect on a client. It stops working at its next token refresh.

For the full picture of how tokens, roles, and tenant isolation protect your data, see Security and trust.

Step 3 — Install the products you need

Once connected to the concierge, let your assistant discover and install products. You don't have to know slugs up front.

💬 Just ask: "What can hdls do?" or "Install the CRM for our workspace." Your assistant calls list_products and install_product for you. You can also browse the full product catalog yourself.

See the catalog (works for everyone):

Tool: list_products
Arguments: {}

This returns every product, the named tools each exposes, its dedicated endpoint, and whether it's already installed in your workspace.

Inspect one product in detail:

Tool: describe_product
Arguments: { "slug": "crm" }

Install it (workspace-level; admin or owner only):

Tool: install_product
Arguments: { "slug": "crm" }

Installing is a one-time, workspace-wide action — once any admin installs crm, it's installed for the whole workspace. Its named tools appear on the next tool listing.

Gotcha — install is workspace-level, connecting is per-machine. Installing a product enables it for the workspace, but each person/machine still adds that product's connector and authenticates on their own assistant. Install once; everyone connects.

Role gating for concierge management tools:

Tool	Who can use it
`list_products`, `describe_product`, `search_skills`, `get_skill`, `help`, `search_docs`	Everyone (any role)
`install_product`, `invite_teammate`	admin / owner
`uninstall_product`	owner only

Step 4 — Add each product as its own connector

For the cleanest experience, connect each product you use as a dedicated MCP server at https://hdls.ai/api/mcp/<slug>. Its tools are named and self-describing, so your assistant knows what to do immediately.

Claude Code (CLI)

claude mcp add --transport http hdls-crm https://hdls.ai/api/mcp/crm -s user

Then authenticate it the same way:

/mcp

The OAuth flow is identical. If you already authorized this product on the concierge, signing in here is quick.

Config-file clients

{
  "mcpServers": {
    "hdls-crm": {
      "url": "https://hdls.ai/api/mcp/crm"
    }
  }
}

Now your assistant has the product's tools

For hdls CRM (/api/mcp/crm), that means tools like:

Tool: create_account
Arguments: { "name": "Acme Inc", "domain": "acme.com" }

Tool: search_accounts
Arguments: { "query": "acme" }

Tool: summarize_account
Arguments: { "id": "<account-id>" }

Notice there's no tenant_id anywhere — it's stamped for you. Each product exposes its own named tools (CRM also has create_contact, create_deal, move_deal_stage, log_activity, and more); call describe_product on the concierge, or list the product connector's tools, to see exactly which fields each accepts.

Heads-up: a product connector only works if that product is enabled for your credential (you ticked it at consent, or it's covered by your API key). If it isn't, the endpoint returns 403. Re-run the connect/authorize flow and include the product, or mint a key scoped to it.

Headless & server-to-server: scoped API keys

For agents and backend jobs that can't do an interactive browser sign-in, use a scoped API key instead of OAuth.

Create one in the console under Connect → Advanced — headless API key (owner / admin only). For each key you choose:

Setting	Options	Default
Product	Any single product (the key works only with that product)	—
Access	read-only / read & write / admin	read & write
Expires	never / 7 / 30 / 90 days	never

The secret is shown once — copy it immediately. It looks like hdls_ followed by a string of url-safe characters.

Use it by sending it as a bearer token. The same key works on the concierge or the product endpoint:

{
  "mcpServers": {
    "hdls-crm": {
      "url": "https://hdls.ai/api/mcp/crm",
      "headers": { "Authorization": "Bearer hdls_your_key_here" }
    }
  }
}

Or as a raw HTTP header your agent sends with every MCP request:

Authorization: Bearer hdls_your_key_here

A key is pinned to one workspace and one product, at the role you chose. Disconnect it any time from the console — any agent using it stops working immediately.

Quick reference

You want to…	Do this
Connect an assistant	Add `https://hdls.ai/api/mcp`, then authorize in the browser
Authenticate in Claude Code	`claude mcp add --transport http hdls https://hdls.ai/api/mcp -s user` then `/mcp`
See what hdls can do	Call `list_products` on the concierge
Turn on a product	`install_product { "slug": "crm" }` (admin/owner)
Use a product's tools	Add `https://hdls.ai/api/mcp/<slug>` as its own connector
Run a backend agent	Mint a scoped API key, send `Authorization: Bearer hdls_…`
Stop a connection	Console → Connect → Disconnect

Common gotchas

Installing a product ≠ being connected. Install is workspace-level; each machine still adds the product connector and authenticates.
You never pass tenant_id. Isolation is automatic; supplying one isn't needed and isn't accepted.
A connection can't exceed your role. Authorize as a reader and the assistant is read-only.
403 from a product endpoint means that product wasn't enabled for your credential — re-authorize and include it, or use a key scoped to it.
install_product, invite_teammate need admin/owner; uninstall_product needs owner. Discovery tools (list_products, describe_product, search_skills) are open to everyone.

Connect your AI assistant

At a glance

The mental model

Step 1 — Add the concierge and sign in

Claude Code (CLI)

Claude Desktop / Cursor / config-file clients

Any other assistant

Step 2 — Authorize (one-click OAuth)

Good to know

Step 3 — Install the products you need

Step 4 — Add each product as its own connector

Claude Code (CLI)

Config-file clients

Now your assistant has the product's tools

Headless & server-to-server: scoped API keys

Quick reference

Common gotchas