WebMCP Architecture & Specs
An enterprise middleware wrapping the W3C MCP standard, featuring dynamic React hook tool registration, strict permission matrices, and automated audit logging.
System & Integration Metrics
Tool Registration
Sub-millisecond unmount/mount cleanup
Auditing Latency
Fire-and-forget POST (non-blocking)
Rate Limiting
Sliding window `sessionStorage` execution
Input Safety
Strict schema typing enforced on every call, before your handler ever runs
1. W3C Polyfill & React Integration
The core of WebMCP is built around injecting capabilities safely into the client session.
- Dynamic React Hook (`useAeionTool`): Component lifecycles dictate tool availability. The hook accepts an AeionToolDefinition and calls navigator.modelContext.registerTool(). When the component unmounts, the hook cleanup function gracefully unregisters the tool, ensuring the AI agent only sees tools relevant to the active UI state.
- The Factory Pattern: For global administration tools (like CRUD operations), createCollectionTools and module-specific factories (createCommerceActions()) define arrays of imperative tool configs, registered in bulk on app initialization via navigator.modelContext.registerTool() — one registration point per module, rather than one useAeionTool call per component.
2. The AeionToolRegistry Middleware
The raw navigator.modelContext API is unsafe for enterprise applications. The AeionToolRegistry wraps the W3C spec to provide mandatory governance.
- AND-Logic Entitlement Checks: Every tool definition can declare an array of required permissions. The Registry intercepts execution, compares the required permissions against the tenantEntitlements injected via the AeionWebMCPProvider, and immediately halts execution if there is a mismatch.
- Automated Audit Logging: Administrators must be able to trace AI actions. The registry attaches a fire-and-forget payload to every execution (success, failure, or permission denial) tracking toolName, userId, durationMs, and status. It posts this telemetry to /api/webmcp/audit, ensuring that the immutable ledger captures all agent interactions without blocking the client thread.
Frequently Asked Questions
Yes — and that's by design intent, not a gap. The client-side sliding window is a guardrail against runaway loops (an agent stuck calling the same tool thousands of times), so it stops the hammering at the source before it ever leaves the tab. It is *not* the security boundary. Every tool ultimately calls the internal API through `aeionFetch` under the user's own authenticated session, so server-side RBAC and the API's own rate limits are the real enforcement. Client throttling protects bandwidth; the server protects data.
No. `useAeionTool` ties a tool's lifetime to the React component's lifecycle — the hook's cleanup function unregisters the tool on unmount, so the agent only ever sees tools relevant to the active UI. Registration and teardown are sub-millisecond, so navigating between pages continuously reshapes the available toolset without cost.
No. The registry attaches a fire-and-forget POST to `/api/webmcp/audit` on every outcome — success, failure, or permission denial — capturing `toolName`, `userId`, `durationMs`, and `status`. It never blocks the client thread or the tool's return, so the ledger captures everything without adding latency to the call.
Run it in the browser when the work is UI-bound or needs a browser-only capability (form-fill, modal flows, clipboard, native file picker). Route it through `aeion_backend_mcp_call` when the operation is heavy or long-running — the bridge forwards a JSON payload to the secured JSON-RPC server endpoint while preserving the same authenticated session, so you never rewrite a tool that already exists server-side.
A serializable object matching the `AeionToolResult` shape — e.g. `{ success: true, data: ... }`. The handler receives typed, schema-validated input (validation runs *before* your code) plus a `ctx` whose `apiClient` is already authenticated with the user's session, so you never touch tokens or keys inside a tool.