Skip to main content

Ask AI assistant widget for Mintlify

Add an AI assistant or AI search widget to your Mintlify documentation using Biel.ai's web components. You can also connect AI agents through MCP, with or without installing the widget.

Prerequisites​

Add the assistant widget​

Assistant widget for docs

  1. Create biel.js beside your docs.json file. Mintlify loads custom JavaScript files from the content directory on every page. No head or scripts entries are needed in the configuration.

    (() => {
      const link = document.createElement('link');
      link.rel = 'stylesheet';
      link.href = 'https://cdn.jsdelivr.net/npm/biel-search/dist/biel-search/biel-search.css';
      document.head.appendChild(link);

      const script = document.createElement('script');
      script.type = 'module';
      script.src = 'https://cdn.jsdelivr.net/npm/biel-search/dist/biel-search/biel-search.esm.js';
      document.head.appendChild(script);

      function addButton() {
        if (document.getElementById('biel-docs-button')) return;
        const button = document.createElement('biel-button');
        button.id = 'biel-docs-button';
        button.setAttribute('project', '<YOUR_PROJECT_ID>');
        button.setAttribute('header-title', 'Biel.ai assistant');
        button.setAttribute('button-position', 'bottom-right');
        button.setAttribute('modal-position', 'bottom-right');
        button.setAttribute('button-style', 'dark');
        button.textContent = 'Ask AI';
        document.body.appendChild(button);
      }

      addButton();
      window.addEventListener('mintlify:navigate', addButton);
    })();

    Replace <YOUR_PROJECT_ID> with your project's ID from the Biel.ai dashboard.

  2. Save the file and run your Mintlify development server:

    mint dev

  3. Open your documentation site and navigate between pages to verify the assistant remains available.

Add the search widget​

  1. Create biel.js beside docs.json to load the widget assets on your pages. If this file already loads Biel.ai, keep those asset lines:

    const stylesheet = document.createElement('link');
    stylesheet.rel = 'stylesheet';
    stylesheet.href = 'https://cdn.jsdelivr.net/npm/biel-search/dist/biel-search/biel-search.css';
    document.head.appendChild(stylesheet);

    const script = document.createElement('script');
    script.type = 'module';
    script.src = 'https://cdn.jsdelivr.net/npm/biel-search/dist/biel-search/biel-search.esm.js';
    document.head.appendChild(script);

  2. Place the search button in an MDX page or custom component where you want readers to search:

    <biel-search-button project="<YOUR_PROJECT_ID>" button-style="rounded">
        Search
    </biel-search-button>

    Replace <YOUR_PROJECT_ID> with your project ID.

  3. Run mint dev, open the page, and test Search with a term from your indexed content. Use the same project ID if you also install the assistant.

Alternative: Using MDX components​

For a button on selected pages, keep the stylesheet and module-loading code in biel.js, but omit addButton() and its navigation listener. Then place the element in an MDX component:

  1. Create a new file components/BielChat.mdx in your Mintlify project:

    <biel-button project="<YOUR_PROJECT_ID>"
        header-title="Biel.ai assistant"
        button-position="bottom-right"
        modal-position="bottom-right"
        button-style="dark">
            Ask AI
    </biel-button>

  2. Import and use this component in any MDX page where you want the assistant to appear.

Connect AI agents with MCP​

Let AI tools search and read your indexed documentation. MCP is available on every plan and during your trial.

  1. In the Biel.ai dashboard, open your project’s Settings > MCP.
  2. Select Enable MCP server and click Save.
  3. In the widget, open Connect via MCP using the <> button. Select your AI client or choose MCP URL to copy the endpoint into its settings.

Without the widget: after enabling MCP, copy MCP endpoint from Settings > MCP and add it to your AI client. No widget installation or website changes are required.

The widget also exposes WebMCP tools to compatible browser agents visiting your site. Use the latest widget release and keep Enable WebMCP selected in Settings > MCP.

Next steps​