Quickstart: Browser-Side AI Tools

For tools tied to a specific React component / page, use the hook:

```tsx import { useAeionTool } from "@aeion/webmcp"; import { z } from "zod";

export function CustomerListPage() { // ... your component ...

useAeionTool({ name: "customer_bulk_archive", description: "Archive multiple customer records by ID. Returns a count of archived records.", inputSchema: { customerIds: z .array(z.string().uuid()) .min(1) .max(1000) .describe("Customer record IDs to archive"), reason: z .string() .min(5) .max(500) .describe("Reason for archival (audit log)"), }, permissions: ["customers:archive"], rateLimit: { maxCalls: 10, windowSeconds: 60 }, handler: async ({ customerIds, reason }, ctx) => { const results = await Promise.allSettled( customerIds.map((id) => ctx.apiClient(/api/v1/customers/${id}/archive, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ reason }), }), ), ); return { success: true, data: { attempted: customerIds.length, succeeded: results.filter((r) => r.status === "fulfilled").length, failed: results.filter((r) => r.status === "rejected").length, }, }; }, });

return <div>...</div>; } ```

The tool is automatically registered with the browser's navigator.modelContext when the component mounts and unregistered when it unmounts. AI agents can call it as long as the user is on the page. The handler's second argument (ctx) carries the current user, tenant, permissions, and a pre-authenticated apiClient — use ctx.apiClient rather than importing your own fetch wrapper, since it's the one the registry's rate-limit and audit pipeline is wired around.

Per-tool permission requirements:

typescript permissions: ["customers:archive", "customers:read"]; // ALL required

For useAeionTool (Step 2), the hook's own registry enforces this: the handler only runs if the current user has every listed permission, otherwise the call short-circuits with { success: false, error: "Insufficient permissions" } before your code ever runs. Module-factory tools (Step 5) are registered imperatively and only get a coarse module-level read-permission check at registration time — if you need the same per-call, per-permission enforcement for a factory tool, check ctx.entitlements / ctx.permissions yourself at the top of execute.

Rate limits:

typescript rateLimit: { maxCalls: 10, // 10 invocations windowSeconds: 60, // per minute }

The tool definition's rateLimit field accepts maxCalls and windowSeconds (per UseAeionToolOptions in @aeion/webmcp). The registry tracks counters per registered tool to surface back-pressure to the AI agent when the limit is hit.

Audit logging — every invocation fires a fire-and-forget audit record (tool name, result, duration, user, tenant, scope — no input payload) that's visible in Admin → Settings → AI Tools → Audit Log, filterable by success/error/denied. Because the automatic path doesn't capture your tool's input arguments, there's nothing to redact by default; if you need a record of exactly what was archived, log that from inside your own handler/execute (e.g., by relying on the target collection's own audit trail on the underlying API call).

For tools available globally (not tied to a specific page), step outside React and create a module factory.

In your module's helper layer, define a factory matching ModuleActionConfig from @aeion/webmcp:

```typescript import type { ModuleActionConfig } from "@aeion/webmcp";

const makeResult = (data: unknown) => ({ content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }], });

export function createMyModuleActions(): ModuleActionConfig[] { return [ { name: "mymodule_bulk_archive", description: "Bulk-archive records of your module's type", category: "custom", permissions: ["mymodule:archive"], inputSchema: { type: "object", properties: { recordIds: { type: "array", items: { type: "string" }, minItems: 1 }, }, required: ["recordIds"], }, execute: async ({ recordIds }, ctx) => { const ids = recordIds as string[]; const results = await Promise.allSettled( ids.map((id) => ctx.apiClient(/api/v1/mymodule/${id}/archive, { method: "POST" }), ), ); return makeResult({ attempted: ids.length, succeeded: results.filter((r) => r.status === "fulfilled").length, failed: results.filter((r) => r.status === "rejected").length, }); }, }, // ... more tools ... ]; } ```

Note the factory itself takes no arguments — the API client comes through as ctx.apiClient on every execute call, not as a constructor parameter. execute also returns the { content: [...] } shape expected by navigator.modelContext.registerTool(), not a bare object.

Factory pattern benefits:

• Tools available everywhere in the admin (not just on specific pages)
• Single registration point per module (easier to audit)
• Testable in isolation
• Can compose multiple low-level API calls into a higher-level tool

Export your factory and register it in the admin's module-tools registry:

```typescript // In the admin's module-tools wire-up import { createMyModuleActions } from "@/modules/mymodule";

export const moduleTools = { mymodule: createMyModuleActions, // ... other modules ... }; ```

Open the admin → Settings → AI Tools. It has three tabs:

• Tools — every tool currently registered for this page/session, with name, category, scope, and an expandable row showing the raw input schema. It also shows two counters: how many tools are Registered in Aeion's internal registry vs. how many the connected agent can actually see via navigator.modelContext.listTools() (Agent sees) — useful for spotting a tool that registered but never made it into the live MCP context.
• Audit Log — every invocation (success / error / denied), filterable by status, with tool name, scope, role, permission required, and duration. Refreshes every 30 seconds.
• About — a reference on tool layers (base tools, collection CRUD, module workflow tools, page-contextual tools) and how to connect an agent.

There's no per-tool disable switch or a "dry-run with synthetic inputs" panel today — to pull a tool temporarily, stop registering it (unmount the component, or remove it from the module factory) and it disappears from navigator.modelContext on its next re-render.

End-to-end verification:

1. Log in as a user with the required permissions
2. Open AeionClaw chat or any AI surface
3. Ask the AI to perform the action ("archive these 5 customers because of reason X")
4. Verify execution succeeds + an entry appears in the Audit Log tab