AbsoluteJS

WebMCP

@absolutejs/webmcpv0.1.5betaAI

Secure WebMCP registration, policy, audit, and test adapters for browser-native AI agent actions.

#Installation

BASH
bun add @absolutejs/webmcp

#Capabilities

Overview

Secure, typed integration with the current WebMCP draft for browser-native AI agent actions.

WebMCP lets a page expose structured tools through document.modelContext.registerTool(). AbsoluteJS keeps that standard surface and adds the controls a production application needs: TypeBox input validation, default-deny authorization over the exact input, approval IDs, metadata poisoning checks, bounded payloads, privacy-preserving audit receipts, secure cross-origin exposure, abort-based cleanup, atomic batch registration, and a spec-shaped test context.

For progressive enhancement in browsers where WebMCP may not be available, use the non-throwing constructor:

Show 3 more

isWebMcpAvailable() is also available for feature-gated UI. Keep using createWebMcpRegistry() when unsupported WebMCP should be treated as a configuration error.

The wrapper targets the July 10, 2026 Community Group draft, including the Document.modelContext location, promise-returning registration, abort-signal unregistration, exact exposedTo origins, and the readOnlyHint and untrustedContentHint annotations. WebMCP is a draft Community Group Report, not yet a W3C Standard; keeping browser access behind WebMcpModelContext isolates draft changes from application code.

Use createWebMcpTestContext() for deterministic unit and conformance tests in Bun or Node. It deliberately adds getTools() and executeTool() only to the test adapter; those methods are not presented as browser-standard APIs.

Same-origin HTTP actions

createWebMcpHttpProjectionDocument() and bootstrapWebMcpHttpActions() project an authenticated application's typed HTTP actions without duplicating its domain implementation in the browser. The bootstrap accepts only origin-relative endpoints on the current trustworthy origin, sends credentials only with same-origin requests, refuses redirects, bounds documents and responses before parsing, validates every tool, and rolls back the complete registration if any tool fails. It never uses exposedTo, so cross-origin frames receive no capability by default.

The HTTP server remains the authorization and audit boundary. The browser registry validates structured input and metadata, but a successful tool call still requires the server's current session, resource, and domain checks.

Specification:

Outcomes

What you can build

Overview

Secure, typed integration with the current WebMCP draft for browser-native AI agent actions.

Same-origin HTTP actions

createWebMcpHttpProjectionDocument() and bootstrapWebMcpHttpActions() project an authenticated application's typed HTTP actions without duplicating its domain implementation in the browser. The bootstrap accepts only origin-relative endpoints on the current trustworthy origin, sends credentials only with same-origin requests, refuses redirects, bounds documents and responses before parsing, validates every tool, and rolls back the complete registration if any tool fails. It never uses exposedTo, so cross-origin frames receive no capability by default.

Hardening checklist

Production guidance

Make every external boundary explicitPin the deployed @absolutejs/webmcp version, replace example or memory-backed dependencies with durable implementations, bound external calls, protect credentials, and emit enough evidence to retry or recover safely.

Follow in order

Troubleshooting path

1
Trace from the first failed boundary
Reproduce the smallest canonical @absolutejs/webmcp example, confirm the supported entry point and version in the API explorer, then inspect the first boundary that did not produce its documented result.

#@absolutejs/webmcp quick start

Partial snippet

# @absolutejs/webmcp

TS
import { createWebMcpRegistry } from "@absolutejs/webmcp";
import { Type } from "@sinclair/typebox";

const tools = createWebMcpRegistry({
  authorize: ({ name, input, annotations }) =>
    agencyDecisionFor({ name, input, annotations }),
  onAudit: (receipt) => audit.write(receipt),
});

await tools.register({
  name: "support.create",
  title: "Create support ticket",
  description: "Create a support ticket after the user confirms the request.",
  inputSchema: Type.Object({ subject: Type.String({ maxLength: 100 }) }),
  annotations: { readOnlyHint: false, untrustedContentHint: true },
  execute: ({ subject }) => createTicket(subject),
});

#@absolutejs/webmcp quick start 2

Partial snippet

# @absolutejs/webmcp

TS
import { tryCreateWebMcpRegistry } from "@absolutejs/webmcp";

const tools = tryCreateWebMcpRegistry({ authorize });
if (tools) await tools.register(tool);

#Same-origin HTTP actions

Partial snippet

createWebMcpHttpProjectionDocument() and bootstrapWebMcpHttpActions() project an authenticated application's typed HTTP actions without duplicating its domain implementation in the browser. The bootstrap accepts only origin-relative endpoints on the current trustworthy origin, sends credentials only with same-origin requests, refuses redirects, bounds documents and responses before parsing, validates every tool, and rolls back the complete registration if any tool fails. It never uses exposedTo, so cross-origin frames receive no capability by default.

TS
const mounted = await bootstrapWebMcpHttpActions({
  manifestPath: "/api/owner/webmcp",
  actionBasePath: "/api/owner/webmcp/actions/",
  formats: {
    uuid: (value) => /^[0-9a-f-]{36}$/iu.test(value),
  },
});

// Unregister every tool when the authenticated page unmounts or signs out.
mounted.dispose();

#Public entry points

Supported entry points declared by this project’s package manifest. Internal dist paths are not part of the package contract.

Public package entry point declared in package.json.

@absolutejs/webmcp@absolutejs/webmcp/manifest@absolutejs/webmcp/manifest.json

#Package commands

Scripts declared by this project’s package manifest.

bun run buildrm -rf dist && bun build src/index.ts src/manifest.ts --outdir dist --target=browser --external @absolutejs/manifest --external @sinclair/typebox && tsc -p tsconfig.build.json && absolute-manifest emit
bun run check:packagebun run format && bun run typecheck && bun run test && bun run build
bun run formatprettier --write "./**/*.{ts,json,md,yml}"
bun run testbun test
bun run typechecktsc --noEmit

#API reference

Search the declarations exported by the current package type files. Expand a symbol to inspect its source-backed signature.

27 symbols
WebMcpAnnotationstypePermalink
TS
type WebMcpAnnotations = {
    readOnlyHint?: boolean;
    untrustedContentHint?: boolean;
};
Exported from @absolutejs/webmcp