Skip to main content
← All docs
UUsable
    usable

    Ask docs chat assistant

    Updated 2026-07-07

    |Open in||History

    What it is

    Each tenant docs site can show an Ask docs button in the header. Clicking it opens a full-height side panel with an embedded Usable Chat assistant scoped to that tenant's documentation workspace.

    Readers ask natural-language questions; the assistant searches published memory fragments in the tenant workspace and answers from that content only (per the embed configuration system prompt).

    This is separate from the MCP HTTP endpoint (/{tenant}/mcp) — the chat panel is for humans in the browser; MCP is for tools like Cursor and scripts.

    How it appears on the site

    On the Usable tenant (/usable locally, docs.usable.dev when deployed):

    1. Open any page under /usable/....
    2. Click Ask docs in the top-right header.
    3. A panel slides in from the right with the chat iframe.
    4. Press Escape or click the backdrop to close.

    The panel is rendered via a React portal (not inside the nav bar) so it uses the full viewport height.

    Configuration (tenant config fragment)

    The embed is not hardcoded in the Next.js repo. It is enabled per tenant in the platform workspace tenant-config YAML fragment (tagged tenant-config):

    tenants:
  - id: usable
    name: Usable
    workspaceId: ef680c43-c6a2-4897-9470-4cf6d3bb204e
    primaryColor: "#6366F1"
    aiEmbedToken: "uc_…"   # embed key from chat.usable.dev
    aiEmbedConfigId: "<uuid>"  # optional; embed config record ID
    FieldPurpose
    aiEmbedTokenuc_… key created on the embed config in Usable Chat. Required for the panel to appear.
    aiEmbedConfigIdUUID of the embed configuration (for future server-side token minting).
    workspaceIdDocs workspace the chat should search — passed to the iframe as workspaces= query param.

    The app builds the iframe URL server-side:

    https://chat.usable.dev/embed?token=<aiEmbedToken>&workspaces=<workspaceId>

    Override the chat host with NEXT_PUBLIC_USABLE_CHAT_URL if needed.

    Security note: aiEmbedToken is stripped from the public /api/tenants response. Only the server layout passes the resolved iframe URL to the client component.

    Setting up Usable Chat (one-time per tenant)

    1. Go to chat.usable.dev → Settings → Embed Configurations → Create.
    2. Name it e.g. Usable Docs Assistant.
    3. Paste a system prompt that scopes answers to published docs in the tenant workspace.
    4. Under Default model, choose General Purpose → Claude Haiku 4.5 (or Gemini 3 Flash). Older Haiku 3.x models may be blocked on Amazon Bedrock as legacy.
    5. Turn off web search, code execution, and library documentation lookup — answers should come from Usable fragments only.
    6. Lock the model so readers cannot switch models.
    7. Create an embed key with allowed domains: localhost:3000, docs.usable.dev, etc.
    8. Copy the uc_… token into tenant config as aiEmbedToken.

    Repeat for other tenants (e.g. Flowcore) with that tenant's workspace ID and embed config.

    Troubleshooting

    SymptomLikely cause
    No Ask docs buttonMissing or placeholder aiEmbedToken in tenant config, or token does not start with uc_.
    Panel cramped in header cornerFixed in app — panel must portal to document.body. Hard-refresh if you see old behavior.
    Bedrock "Legacy model" errorEmbed config uses Claude 3 Haiku; switch to Claude Haiku 4.5 in embed settings.
    Chat loads but answers are wrong tenantCheck workspaceId in tenant config matches the docs workspace.
    Key rejected / blank iframeEmbed key allowed domains must include your origin (e.g. localhost:3000).

    For AI agents: use MCP instead

    Developers and IDE agents should prefer the MCP server over the chat iframe:

    EndpointUse
    GET /usable/mcpDiscovery (tools list)
    POST /usable/mcpJSON-RPC: search_docs, get_page, list_pages
    /usable/llms.txtCurated page index for LLMs
    /usable/<slug>.mdRaw markdown export per page

    Example:

    curl -X POST http://localhost:3000/usable/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_docs","arguments":{"query":"ask docs"}}}'

    See also: Authoring and publishing documentation for how fragments become pages.

    What to try

    • Open /usable/ask-docs-chat-assistant.md for this page as raw markdown.
    • Click Ask docs and ask: How do I publish a new page?
    • Compare with MCP list_pages for the same tenant.