---
title: "Browser agents"
description: "Tools that agents in the visitor's browser can call, through WebMCP."
canonical_url: "https://docs.dev.lightdrop.cloud/guides/browser-agents"
---
# Browser agents

> Tools that agents in the visitor's browser can call, through WebMCP.

[WebMCP](https://github.com/webmachinelearning/webmcp) lets a page hand tools to an agent running
in the browser. Instead of clicking through the UI, the agent calls the app's functions directly,
as the signed-in visitor. In a wervt app, every file in `server/tools/` is such a tool:

```ts [server/tools/add-todo.ts]
import { defineTool, useDb } from '@wervt/nuxt/server'
import * as v from 'valibot'
import { todos } from '../db/schema'

export default defineTool({
  description: 'Add a todo. Returns the new todo.',
  input: { title: v.pipe(v.string(), v.trim(), v.nonEmpty(), v.maxLength(200)) },
  async handler(event, input) {
    const [todo] = await useDb().insert(todos).values(input).returning()
    return todo
  },
})
```

```ts [server/tools/list-todos.ts]
import { defineTool, useDb } from '@wervt/nuxt/server'
import { desc } from 'drizzle-orm'
import { todos } from '../db/schema'

export default defineTool({
  description: 'List all todos, newest first, with their id, title and whether they are done.',
  readOnly: true,
  handler: () => useDb().select().from(todos).orderBy(desc(todos.createdAt)),
})
```

The file path is the tool's name: `server/tools/add-todo.ts` is `add-todo`,
`server/tools/todos/add.ts` is `todos.add`; `name` overrides it.

- **description:** what the tool does, what it returns and where ids come from. The agent picks
tools by it.
- **input:** a valibot schema or a `{ key: schema }` object, like the
[validation helpers](https://docs.dev.lightdrop.cloud/api/validation). The agent gets it as JSON Schema; the handler gets
the validated, typed output. Invalid input returns the issues to the agent, which can correct
its call. Omit `input` for tools without arguments.
- **readOnly:** the tool only reads. Agents may call such tools without asking the user.

[Nuxt layers](https://nuxt.com/docs/guide/going-further/layers) bring their tools along: the
`server/tools/` of every layer the app extends (including `layers/*/`) counts too. When the app
and a layer have a tool with the same name, the app's wins, as with other layer files.

## API routes as tools

Most tools do what an API route already does. Declare the tool on the route with
`defineToolRoute` instead, so logic and validation exist once:

```ts [server/api/todos/[id].patch.ts]
import { defineToolRoute, useDb, vh } from '@wervt/nuxt/server'
import { eq } from 'drizzle-orm'
import { createError } from 'nuxt/server'
import * as v from 'valibot'
import { todos } from '../../db/schema'

export default defineToolRoute({
  tool: { name: 'update-todo', description: 'Mark a todo done or not done. Ids from list-todos.' },
  params: { id: vh.id },
  input: { done: v.boolean() },
  async handler(event, { id, done }) {
    const [todo] = await useDb().update(todos).set({ done }).where(eq(todos.id, id)).returning()
    if (!todo) throw createError({ status: 404, message: `No todo with id ${id}` })
    return todo
  },
})
```

- As a route, `params` are validated from the URL and `input` from the body (the query for GET
routes); as a tool, the agent sends both as one JSON object. The handler gets them merged.
Both must be `{ key: schema }` objects (or `v.object`).
- `tool.name` defaults to the path and method (`todos.id.patch`), so set a readable one.
`tool.readOnly` defaults to true for GET routes.
- `@wervt/nuxt` finds such routes in `server/api/` and `server/routes/`, layers included, when
the server builds; in `nuxt dev` adding or removing `defineToolRoute` restarts the server.

The app template has both: `add-todo` and `update-todo` on its routes, `list-todos` in
`server/tools/`.

## How it works

1. When the page loads in a browser with WebMCP, `@wervt/nuxt` fetches the tool list from
`/_wervt/tools` and registers each tool with `document.modelContext`. Other browsers skip this,
without an extra request.
2. When the agent calls a tool, the page sends the arguments to `/_wervt/tools/<name>`, which
validates them and runs the handler.
3. Changes show up on the page through [live data](https://docs.dev.lightdrop.cloud/guides/live-data), like any other write.

A tool runs with the visitor's cookies, so it sees the same user as an API route: check
`useWervtUser(event)` and ownership in the handler as the matching route does. The run route
only accepts requests from the app's own pages, so other sites can't call tools for a visitor.
Each call is logged with the request's wide event, with a `tool` field.

The same tools are served at `/mcp` to AI clients outside the browser, like Claude Code (see
[App MCP](https://docs.dev.lightdrop.cloud/guides/mcp)).

To build an app without tools, delete `server/tools/`. `wervt: { webmcp: false }` in
`nuxt.config.ts` keeps them away from browser agents, `wervt: { mcp: false }` from MCP clients.


## Sitemap

See the full [sitemap](https://docs.dev.lightdrop.cloud/sitemap.md) for all pages.
