In short: npm install @leuria/docusaurus, add "@leuria/docusaurus" to plugins, run your site. That's the whole setup. The rest of this tutorial shows what readers see, the options worth turning on, and how to add a fallback for readers who have no AI of their own.

You can try the result on this page: the Ask AI button at the top answers from the Leuria docs.

What you need​

• A Docusaurus 3 site (3.6 or later).
• Five minutes.
• To try it with your own AI: the Leuria app (Mac or Windows), or npx @leuria/cli in a terminal.

Step 1: install the plugin​

npm install @leuria/docusaurus

Step 2: add it to your config​

export default {
  // ...
  plugins: [
    [
      "@leuria/docusaurus",
      {
        suggestions: ["How do I get started?", "How do I deploy?"],
      },
    ],
  ],
}

suggestions are the questions the panel offers before the first one. Write the two or three questions your readers ask most.

Step 3: run your site​

npm start

The navbar now has an Ask AI button. At build time the plugin read the Markdown of every docs page (drafts and unlisted pages left out) and cut it into sections. Readers fetch that file the first time they ask.

Step 4: ask with your own AI​

1. Open the Leuria app. The first time, it asks which AI to use: an app you already pay for (ChatGPT, Claude), a model on your computer (LM Studio, Ollama), or an AI service with a key.
2. On your site, click Ask AI, then Connect your AI.
3. Allow your site in the window Leuria opens.

Ask a question. The assistant calls the docs tools (search_docs, read_page, list_pages, open_page), reads the pages it needs, and answers with links. It knows which page the reader has open and the text they selected. The conversation stays open while the reader moves between pages.

Step 5: turn on the options worth having​

plugins: [
  [
    "@leuria/docusaurus",
    {
      app: "Acme docs",          // the name readers see when they connect your site
      suggestions: ["How do I get started?"],
      search: true,              // a ⌘K search, by words and by meaning (for sites without one)
      connectButton: true,       // "Connect your AI" in the navbar
      pageEmbeddings: true,      // search by meaning for readers whose AI can't embed (npm install @leuria/web-embed)
    },
  ],
],

• Already on Algolia DocSearch or a local search plugin? Leave search off. The plugin replaces no theme component, so it works next to your search.
• pageEmbeddings downloads a small embedding model (about 40 MB) only when the reader agrees.
• Versioned docs work as they are: the assistant stays in the version the reader is on.

Every option is in the plugin reference.

Step 6 (optional): a fallback for readers with no AI​

Readers without Leuria are offered it first. Below, in small, they can pick another AI for the page:

• The browser's built-in model, where there is one (Chrome with its AI features on). It can't use tools, so the panel searches your docs itself and gives the model the best passages.
• Your own server, if you set server. It must speak the OpenAI Chat Completions API, and add the API key on the server side:

["@leuria/docusaurus", {
  server: { url: "https://ai.example.com/v1/chat/completions", model: "docs-fallback", label: "Acme's AI" },
}]

Everything in server reaches the page, so never put a key there. The LiteLLM tutorial builds that endpoint, with a budget and a rate limit.

Step 7 (optional): llms.txt for coding agents​

The Ask panel serves people. Coding agents (Cursor, Claude Code, Codex) read your docs better as Markdown. Add docusaurus-plugin-llms next to it:

npm install docusaurus-plugin-llms

plugins: [
  ["@leuria/docusaurus", { suggestions: ["How do I get started?"] }],
  ["docusaurus-plugin-llms", { generateMarkdownFiles: true }],
],

It writes /llms.txt, /llms-full.txt and a Markdown copy of every page at build time. This site does the same: see leuria.dev/llms.txt.

The docs tools also go to the agents built into the browser, through WebMCP. That's on by default (webmcp: true).

How it works​

• Your site stays static. There is no server of yours in the loop, unless you set server.
• The docs index stays in the reader's browser.
• The reader's AI only gets your docs tools. Through Leuria it runs with its own tools switched off, in an empty folder.

Hosted Ask AI or the reader's own AI?​

A hosted docs assistant answers with an API key the site pays for, so every question costs you something. With Leuria, the reader's AI answers: a ChatGPT or Claude plan they already pay for, or a model on their own computer that costs nobody anything. You can still keep a hosted model as the last resort with server.

FAQ​

Does it work for readers who don't have Leuria? Yes. They're offered Leuria first, and can pick the browser's built-in model or your server instead, for the page.

Which AIs can readers use? ChatGPT (through Codex), Claude (through Claude Code), any model in LM Studio or Ollama, and any OpenAI-compatible API they have a key for.

Does my content go to a third party? Only to the AI the reader chose. Questions never reach your server unless you set server and nothing else can answer.

Does it replace my search? No. It sits next to Algolia DocSearch or a local search. Turn on search: true only if your site has none.

Do I need to change my Markdown? No. The plugin reads your docs as they are.

What does it cost? Nothing per question. The plugin is open source (Apache-2.0).

Next​

• Use Ollama in a web app, without CORS or API keys: the reader side, with a model on their computer.
• LiteLLM as your docs assistant's fallback: the server side.
• Plugin reference: every option.

Written for @leuria/docusaurus 0.1.2 and Docusaurus 3.10.

In short: add Leuria to your page (one script from a CDN). A visitor with Ollama installs the Leuria app, picks an Ollama model, and allows your site once. From then on, your AI features run on their model, on their computer.

Why not call Ollama from the page?​

The usual way is to fetch("http://localhost:11434/api/chat") from the browser. That breaks for real visitors:

• CORS. Ollama refuses browser requests from origins it doesn't know. Each visitor would have to set OLLAMA_ORIGINS for your site and restart Ollama.
• No consent. Any page the visitor opens could use their model the same way.
• One AI only. Visitors who use ChatGPT, Claude or LM Studio instead get nothing.

With Leuria, the browser never calls Ollama. The Leuria app, on the visitor's computer, does. It answers only the sites the visitor allowed, and gives the model only the tools your page offers.

Part 1, for site builders: add Leuria to your page​

One file, no build step:

<!doctype html>
<leuria-connect-button></leuria-connect-button>
<p><input id="question" placeholder="Ask something"> <button id="ask">Ask</button></p>
<p id="answer"></p>

<script type="module">
  import { leuria, promptAPI, createAI, setDefaultClient } from "https://cdn.jsdelivr.net/npm/@leuria/connect/dist/standalone.js"

  // The visitor's own AI first (their Ollama model, or another AI they chose), then the browser's built-in model.
  const ai = createAI({
    providers: [leuria({ app: "My site", needs: { effort: "light" } }), promptAPI()],
  })
  setDefaultClient(ai)

  document.querySelector("#ask").onclick = async () => {
    const answer = document.querySelector("#answer")
    answer.textContent = ""
    for await (const event of ai.chat({ prompt: document.querySelector("#question").value })) {
      if (event.type === "text-delta") answer.textContent += event.text
    }
  }
</script>

<leuria-connect-button> handles the whole connect flow. needs tells Leuria what your feature needs, so it recommends the smallest of the visitor's models that is enough: a short answer doesn't need a 70B model.

On Docusaurus, the Ask AI plugin does all this for you.

Give the model tools​

Ollama models trained for tool calling (Qwen 3, Llama 3.1, gpt-oss…) can call functions in your page:

const listMugs = {
  name: "list_mugs",
  description: "List the mugs for sale, with their price in euros.",
  inputSchema: { type: "object", properties: {} },
  execute: () => [{ name: "Celadon", price: 24 }, { name: "Tenmoku", price: 31 }],
}

const answer = await ai.chat({ prompt: "Which mug is cheapest?", tools: [listMugs] }).text()

The tool runs in the page. The model only sees what it returns. Declare needs: { tools: true } so Leuria recommends a model that can call tools. See Page tools.

Part 2, for Ollama users: let your model answer on websites​

1. Pull a chat model​

ollama pull qwen3:8b

Any chat model works. For sites with tools (Ask AI on docs, shops), pick one trained for tool calling. 4B to 8B models handle light tasks well.

2. Install Leuria​

Download it from leuria.eu/download (Mac and Windows), or with Homebrew:

brew tap leur-ia/leuria https://github.com/leur-ia/leuria
brew install --cask leuria

On Linux, run the engine from a terminal: npx @leuria/cli@latest.

3. Choose your Ollama model​

Open Leuria. Under Add an AI, choose A model on this computer. Leuria finds Ollama at its usual address and lists your models. Pick one. You can change it later, for every site or for one site.

If Ollama isn't listed, make sure it runs (the Ollama app is open, or ollama serve), then click Look again.

4. Allow a site​

On a site that uses Leuria (try demo.leuria.dev), click Connect your AI and allow the site in Leuria's window. Its AI features now run on your model.

Search by meaning: add an embedding model​

Sites that search by meaning (the Docusaurus plugin's search, for one) use an embedding model on your computer when you have one:

ollama pull nomic-embed-text

Leuria finds it on its own. Embeddings only ever use a model on your computer, never a service on the network.

Ollama cloud models​

Ollama also lists the cloud models you signed in to, which run on ollama.com. Leuria shows them, but doesn't count them as on this computer when it recommends a model.

Troubleshooting​

Leuria says "No model found on this computer". Ollama isn't running, or has no chat model yet. Start Ollama, run ollama list to check, then click Look again.

Do I need OLLAMA_ORIGINS or OLLAMA_HOST? No. The browser never calls Ollama. Leuria calls it from the same computer, at 127.0.0.1:11434.

Ollama runs on another port or machine. Add it as a service with its address: in Leuria, Add an AI → An AI service with a key → Another service, address http://<host>:<port>/v1. Or from a terminal: npx @leuria/cli providers add "My Ollama" http://<host>:<port>/v1.

Answers say the model can't use the site's tools. Pick a model trained for tool calling, such as qwen3:8b.

FAQ​

Does my data leave my computer? With an Ollama model on your computer, no: the site's page sends the question to Leuria, Leuria to Ollama, both on your computer.

Can a website use my model without asking? No. A site must ask, and you allow it in Leuria's own window. You can disconnect it at any time.

What does it cost the website? Nothing. The visitor's model answers.

Next​

• LiteLLM as your docs assistant's fallback: for visitors with no AI of their own.
• Use LM Studio models on any website.
• Providers and the cascade: who answers, and when.

Written for Leuria 0.1.4 and @leuria/client 0.1.4.

In short: run LiteLLM with one model alias and a virtual key capped by budget and rate. Put a tiny proxy in front that adds the key and allows only your site. Point server() (or the Docusaurus plugin's server option) at the proxy, with model set.

The cascade​

Your gateway answers only when the visitor has no AI of their own and picks yours. So the bill stays small, and the cap keeps it that way.

What you need​

• A server that can run Docker, reachable over HTTPS (any small VPS).
• An API key for a model provider (OpenAI, Anthropic, Mistral…), or your own vLLM or Ollama server.
• A free Cloudflare account for the proxy, or any place that runs a small function.

Step 1: run LiteLLM with one model alias​

Expose one alias, docs-fallback, so you can swap the model behind it without touching your site.

model_list:
  - model_name: docs-fallback
    litellm_params:
      model: mistral/mistral-small-latest # or openai/…, anthropic/…, hosted_vllm/…
      api_key: os.environ/MISTRAL_API_KEY

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  database_url: os.environ/DATABASE_URL # virtual keys and budgets need a database

services:
  litellm:
    image: docker.litellm.ai/berriai/litellm:latest
    command: ["--config", "/app/config.yaml"]
    volumes: ["./litellm_config.yaml:/app/config.yaml:ro"]
    ports: ["4000:4000"]
    environment:
      MISTRAL_API_KEY: ${MISTRAL_API_KEY}
      LITELLM_MASTER_KEY: ${LITELLM_MASTER_KEY}
      DATABASE_URL: postgresql://litellm:litellm@db:5432/litellm
    depends_on: [db]
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: litellm
      POSTGRES_DB: litellm
    volumes: ["pgdata:/var/lib/postgresql/data"]
volumes:
  pgdata:

export MISTRAL_API_KEY=... LITELLM_MASTER_KEY=sk-$(openssl rand -hex 16)
docker compose up -d

Put LiteLLM behind HTTPS (Caddy, nginx, or your host's load balancer).

Step 2: create a capped key for your site​

The master key never leaves your server. Make a virtual key that can only use docs-fallback, with a budget and a rate limit:

curl -X POST https://llm.example.com/key/generate \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key_alias": "docs-fallback",
    "models": ["docs-fallback"],
    "max_budget": 10,
    "budget_duration": "30d",
    "rpm_limit": 30
  }'

That's $10 a month (LiteLLM counts in US dollars) and 30 requests a minute, at most. When the budget is spent, the gateway refuses, and readers are offered Leuria and the browser's model as before.

Step 3: a proxy that adds the key​

Everything you give server() reaches the page, so the key can't go there. A Cloudflare Worker sits between the page and LiteLLM. It allows only your site's origin, forces the model and caps the answer's length:

export default {
  async fetch(request, env) {
    const cors = {
      "Access-Control-Allow-Origin": env.SITE_ORIGIN,
      "Access-Control-Allow-Methods": "POST, OPTIONS",
      "Access-Control-Allow-Headers": "Content-Type",
      Vary: "Origin",
    }
    const allowed = request.headers.get("Origin") === env.SITE_ORIGIN
    if (request.method === "OPTIONS") return new Response(null, { status: allowed ? 204 : 403, headers: cors })
    if (request.method !== "POST" || !allowed) return new Response("Forbidden", { status: 403 })

    const body = await request.json()
    body.model = "docs-fallback"
    body.max_tokens = Math.min(body.max_tokens ?? 1024, 1024)

    const upstream = await fetch(`${env.LITELLM_URL}/v1/chat/completions`, {
      method: "POST",
      headers: { "Content-Type": "application/json", Authorization: `Bearer ${env.LITELLM_KEY}` },
      body: JSON.stringify(body),
    })
    return new Response(upstream.body, {
      status: upstream.status,
      headers: { ...cors, "Content-Type": upstream.headers.get("Content-Type") ?? "text/event-stream" },
    })
  },
}

npx wrangler deploy worker.js --name docs-ai
npx wrangler secret put LITELLM_KEY        # the virtual key from step 2
npx wrangler secret put LITELLM_URL        # https://llm.example.com
npx wrangler secret put SITE_ORIGIN        # https://docs.example.com

The origin check stops other websites from using your gateway from their pages. It doesn't stop a script that fakes the header: the budget and the rate limit on the key do.

Step 4: point your site at it​

Docusaurus, with the Ask AI plugin:

plugins: [
  [
    "@leuria/docusaurus",
    {
      suggestions: ["How do I get started?"],
      server: {
        url: "https://docs-ai.<you>.workers.dev",
        model: "docs-fallback",
        label: "Acme's AI",
      },
    },
  ],
],

Any other site, with the SDK:

import { createAI, leuria, promptAPI, server } from "@leuria/client"

const ai = createAI({
  providers: [
    leuria({ app: "Acme docs" }),                       // the visitor's own AI first
    promptAPI(),                                         // the browser's built-in model
    server({ url: "https://docs-ai.<you>.workers.dev", model: "docs-fallback", label: "Acme's AI" }),
  ],
})

Set model: LiteLLM doesn't pick one for you. (@leuria/docusaurus sends it from 0.1.2.)

Step 5: try it​

1. Open your site in a browser without Leuria.
2. Click Ask AI. The panel proposes Leuria first.
3. Pick Acme's AI below. Ask a question.

Each request shows up in LiteLLM's spend logs under the docs-fallback key.

To make your gateway answer at once for readers without Leuria, instead of after they pick it, set fallback: "auto".

Options worth knowing​

• Tools. The docs tools (search_docs, read_page) still run in the page: your gateway only relays the model's tool calls. Choose a model that calls tools well. If yours can't, set tools: false.
• Structured output. If your model supports response_format: { type: "json_schema" }, set jsonSchema: true.
• Images. Set images: true if the model reads images.

The same with vLLM, Ollama or oMLX on your server​

Anything that speaks the OpenAI Chat Completions API with streaming works behind the proxy:

• vLLM: vllm serve <model> --served-model-name docs-fallback --enable-auto-tool-choice --tool-call-parser <parser>, then add it to LiteLLM's model_list with model: hosted_vllm/docs-fallback and api_base: http://<vllm-host>:8000/v1.
• Ollama or oMLX on a server: same, with their /v1 address. Keep them behind the proxy too: neither should face the internet without a key.

Going through LiteLLM keeps the budget, the rate limit and the spend logs in one place.

FAQ​

Why not call LiteLLM straight from the page with the virtual key? The key would be in your site's JavaScript, for anyone to copy and use anywhere. The proxy keeps it on the server.

Does my gateway see questions from visitors who use their own AI? No. Those go from the page to Leuria on the visitor's computer, then to their AI.

What happens when the budget runs out? The gateway refuses. Readers can still connect their own AI or use the browser's model.

Can I use OpenRouter instead of LiteLLM? Yes. The proxy is the same: put your OpenRouter key in the Worker and pick the model there.

Next​

• Use Ollama in a web app, without CORS or API keys: the visitor's side.
• Going to production: limits, privacy, Content-Security-Policy.

Written for @leuria/docusaurus 0.1.2, @leuria/client 0.1.4 and LiteLLM's latest image.

In short: add Leuria to your site. A visitor with LM Studio starts its local server, installs the Leuria app and picks a model. Your AI features then run on that model, on their computer.

Why not call LM Studio from the page?​

You could turn on Enable CORS in LM Studio and fetch("http://localhost:1234/v1/chat/completions") from your page. It works on your machine. For real visitors:

• each one has to find that switch, and then every page they open can use their model, without asking;
• visitors who use Ollama, ChatGPT or Claude get nothing.

With Leuria, the browser never calls LM Studio. The Leuria app does, from the same computer, for the sites the visitor allowed, with only the tools your page offers. LM Studio's settings stay as they are.

Part 1, for site builders​

Add Leuria to your page. With a bundler:

npm install @leuria/client @leuria/connect

import { createAI, leuria, promptAPI, defineTool } from "@leuria/client"
import { setDefaultClient } from "@leuria/connect" // defines <leuria-connect-button>

const ai = createAI({
  providers: [
    leuria({ app: "Recipe box", needs: { tools: true, effort: "light" } }),
    promptAPI(),
  ],
})
setDefaultClient(ai)

const findRecipes = defineTool<{ ingredient: string }>({
  name: "find_recipes",
  description: "Find recipes that use an ingredient. Returns titles and links.",
  inputSchema: { type: "object", properties: { ingredient: { type: "string" } }, required: ["ingredient"] },
  execute: ({ ingredient }) => recipes.filter((r) => r.ingredients.includes(ingredient)),
})

const answer = await ai.chat({ prompt: "What can I cook with leeks?", tools: [findRecipes] }).text()

Put <leuria-connect-button></leuria-connect-button> in your page. Without a bundler, the Ollama tutorial has a one-file version from a CDN.

Say what your feature needs​

needs matters more with LM Studio than anywhere else. Leuria reads what LM Studio reports about each model (loaded or not, trained for tool use, reads images, context length, size) and recommends the smallest one that fits your site. A visitor with a 70B model and a 4B model loaded gets the 4B one recommended for a light task, and their machine stays responsive.

• tools: true if your feature uses tools.
• effort: light (answer, extract, summarize), standard (several steps with tools), deep (long reasoning).

See Declare what your features need.

Part 2, for LM Studio users​

1. Start LM Studio's local server​

In LM Studio, open the Developer tab and start the server. Or from a terminal:

lms server start

Leave the port at 1234. Download a chat model if you have none yet: for sites with tools, one trained for tool use (LM Studio marks them).

2. Install Leuria​

From leuria.eu/download (Mac and Windows), or with Homebrew:

brew tap leur-ia/leuria https://github.com/leur-ia/leuria
brew install --cask leuria

3. Choose your LM Studio model​

Open Leuria, Add an AI, A model on this computer. Leuria lists your LM Studio models and suggests one that is already loaded. Pick one. When a site asks, Leuria shows which model it recommends for that site, and why.

4. Allow a site​

On a site that uses Leuria (try demo.leuria.dev), click Connect your AI and allow it in Leuria's window.

Search by meaning with an LM Studio embedding model​

Download an embedding model in LM Studio (for example a nomic-embed-text build). Leuria finds it, and sites that search by meaning use it on your computer. Embeddings only ever use a model on your computer.

Troubleshooting​

Leuria says "No model found on this computer". LM Studio's server isn't running. Start it in the Developer tab or with lms server start, then click Look again.

Do I need to turn on "Enable CORS" or "Serve on local network"? No. Leuria calls LM Studio from the same computer, at 127.0.0.1:1234.

LM Studio runs on another port or another machine. Add it as a service: Add an AI → An AI service with a key → Another service, with its address (http://<host>:<port>/v1).

The first answer is slow. The model is loading. Leuria prefers models that are already loaded: load the one you use most in LM Studio.

FAQ​

Does anything leave my computer? No. The page sends the question to Leuria, Leuria to LM Studio, both on your computer.

Can sites use my model without asking? No. Each site must ask, and you allow it in Leuria's own window. You can disconnect it at any time.

Can I use a different model per site? Yes. In Leuria's Websites tab, change the AI for one site.

Next​

• Use Ollama in a web app, without CORS or API keys.
• Run oMLX models on websites, on Apple Silicon.
• Page tools.

Written for Leuria 0.1.4 and @leuria/client 0.1.4.

In short: start oMLX (it listens on http://localhost:8000/v1), then in Leuria add it as a service with that address. Sites you allow then answer with your MLX model.

Why MLX for this​

MLX runs models on the Mac's unified memory and GPU, and is often the fastest way to run a model on an M-series Mac. oMLX adds what a website's AI features need: streaming, tool calling, and continuous batching, so two sites can ask at once.

Part 1: start oMLX​

Install the app from oMLX's releases, or with Homebrew:

brew tap jundot/omlx https://github.com/jundot/omlx
brew install jundot/omlx/omlx

Start the server with a folder of MLX models:

omlx serve --model-dir ~/models

Or start it from the menu bar app. Download a model from its dashboard (http://localhost:8000/admin). For sites with tools, pick one trained for tool calling, such as a Qwen 3 MLX build.

Check that it answers:

curl http://localhost:8000/v1/models

oMLX needs macOS 15 or later on Apple Silicon.

Part 2: add oMLX to Leuria​

Install Leuria from leuria.eu/download, or:

brew tap leur-ia/leuria https://github.com/leur-ia/leuria
brew install --cask leuria

Then open Leuria:

1. Add an AI → An AI service with a key.
2. Service: Another service (your company's AI…).
3. Name: oMLX. Address: http://localhost:8000/v1. Leave API key empty, unless you set one in oMLX.
4. Connect this service, then pick a model.

From a terminal instead:

npx @leuria/cli providers add oMLX http://localhost:8000/v1

Leuria lists oMLX with your AI services. You can make it your default, or use it for some sites only.

Part 3: allow a site​

On a site that uses Leuria (try demo.leuria.dev), click Connect your AI and allow it. Leuria asks oMLX, on your Mac. Nothing leaves it.

For site builders: oMLX as your site's fallback​

A Mac mini running oMLX can also be your site's own AI, for visitors who have none. Put it behind the proxy from the LiteLLM tutorial, never straight on the internet: the proxy holds the key, allows only your site and caps usage. oMLX itself refuses to listen beyond your Mac without an API key.

server({ url: "https://docs-ai.<you>.workers.dev", model: "<your oMLX model id>", label: "Acme's AI" })

Set model to the id curl http://localhost:8000/v1/models returns.

Troubleshooting​

"Connected, but this service lists no chat model." oMLX found no model in its folder. Download one from its dashboard, or check --model-dir.

Leuria can't reach oMLX. Check that curl http://localhost:8000/v1/models answers. If you started oMLX on another port, use that port in the address.

Search by meaning doesn't use my oMLX embedding model. Leuria uses embedding models from LM Studio or Ollama. Sites that search by meaning still work by words, or with their own in-page model.

FAQ​

Is oMLX better than Ollama or LM Studio for this? Use the one you already have. Leuria works with all three, and you can switch per site.

Does it work on Intel Macs? No: MLX needs Apple Silicon. Use Ollama or LM Studio there.

Next​

• Use LM Studio models on any website.
• Page tools, WebMCP and skills: what your site can give the visitor's AI.

Written for Leuria 0.1.4.

In short: define tools with defineTool. Pass them to ai.chat() or a conversation for the visitor's AI, and to exposeTools() for the browser's agents. Add skills to leuria() to give the visitor's AI your site's know-how.

Step 1: define a tool​

A tool is a name, a description, a JSON Schema for its arguments, and a function that runs in the page:

import { defineTool } from "@leuria/client"

export const searchProducts = defineTool<{ query: string }>({
  name: "search_products",
  description: "Search the catalog. Returns name, price in euros and stock.",
  inputSchema: { type: "object", properties: { query: { type: "string" } }, required: ["query"] },
  annotations: { readOnlyHint: true },
  execute: ({ query }, { signal }) => catalog.search(query, { signal }),
})

export const addToCart = defineTool<{ sku: string; quantity: number }>({
  name: "add_to_cart",
  description: "Add a product to the visitor's cart.",
  inputSchema: {
    type: "object",
    properties: { sku: { type: "string" }, quantity: { type: "integer", minimum: 1 } },
    required: ["sku", "quantity"],
  },
  annotations: { consequentialHint: true },
  execute: ({ sku, quantity }) => cart.add(sku, quantity),
})

The AI never runs code of its own on your page. It asks for a tool call, your function runs with the page's rights, and the AI sees only what it returns. Validate arguments as you would a form.

Step 2: the visitor's own AI uses them​

import { createAI, leuria, promptAPI } from "@leuria/client"

const ai = createAI({
  providers: [leuria({ app: "Kiln & Co.", needs: { tools: true, effort: "standard" } }), promptAPI()],
})

const chat = ai.conversation({
  system: "You are the shop's assistant. Use the tools; never invent a product.",
  tools: [searchProducts, addToCart],
})

await chat.send("Add two of your cheapest blue mugs to my cart").result()

The visitor's AI (ChatGPT, Claude, an Ollama or LM Studio model) gets these tools and only these: through Leuria it runs with its own tools off, in an empty folder.

Ask before anything that matters​

Leave out execute, and the call waits for your UI. The visitor confirms, then you answer the call:

const placeOrder = defineTool<{ total: number }>({
  name: "place_order",
  description: "Place the order. The visitor confirms first.",
  inputSchema: { type: "object", properties: { total: { type: "number" } }, required: ["total"] },
})

chat.subscribe(() => {
  for (const input of chat.getState().pendingInputs)
    confirmDialog(input.args, (ok) => (ok ? chat.submitToolResult(input.callId, { placed: true }) : chat.rejectToolCall(input.callId)))
})

Step 3: the browser's agents use them too (WebMCP)​

WebMCP lets a page offer tools to the agent built into the browser. The same tool objects work there:

import { exposeTools } from "@leuria/client"

const takeBack = exposeTools([searchProducts, addToCart])
// later, to withdraw them: takeBack()

• Where the browser has no WebMCP, nothing happens.
• The annotations tell the browser's agent which tools only read (readOnlyHint), which do something that matters (consequentialHint), and which return text you don't control (untrustedContentHint).
• Tools without execute are left out: they need your UI.
• In React: useExposedTools(tools) from @leuria/react.

To try it, Chrome ships WebMCP behind chrome://flags/#enable-webmcp-testing, and to sites through an origin trial from Chrome 149.

On Docusaurus, the Ask AI plugin already offers its docs tools through WebMCP (webmcp: true by default).

Step 4: guide the AI with skills​

Tools say what the AI can do. Skills say how your site works: how returns go, what to ask first, which tool to call when. A skill is a folder with a SKILL.md, in the Agent Skills format:

---
name: returns
description: "How to prepare a return request, from the order number to the label."
---

Ask for the order number, then call `find_order`. Returns are free within 30 days.

Then list your skills in .well-known/agent-skills/index.json (see the discovery index), and pass them to leuria():

leuria({
  app: "Kiln & Co.",
  skills: [
    "/",                                                       // your own, from /.well-known/agent-skills
    "vercel-labs/agent-skills@web-design-guidelines#9f2c1e4",  // a shared skill, pinned to a commit
  ],
})

On Docusaurus: ["@leuria/docusaurus", { skills: ["/"] }].

What happens next:

• When your site asks to connect, Leuria fetches the skills and shows them to the visitor ("This site uses 2 skills to guide your AI", with See details).
• The AI gets each skill's name and description, and a read_skill tool to read the full instructions when a request matches. Long skills cost nothing until they're needed.
• Pin shared skills to a commit (#<sha>): a branch can change under you.

Skills only reach the visitor's own AI, through Leuria. For the browser's model and your server, put what they need in system.

Which AI gets what​

FAQ​

What's the difference between WebMCP and MCP? MCP connects an AI to tools on a server. WebMCP lets a web page offer tools to an AI in the browser, running in the page with the visitor's session.

Can the AI call my tools with any arguments? Yes. Treat arguments as untrusted input. Take the account or the page from the turn's context (send(text, { context })), never from the model's arguments.

Do skills give the AI new permissions? No. Skills are instructions. The AI can still only call your page's tools.

Next​

• Page tools: middleware, terminal tools, limits.
• Skills: refs, the discovery index, caching.
• Tool builder: write a tool's schema in the browser.

Written for @leuria/client 0.1.4.