Expose page features as in-browser tools with ak:webmcp

Use ak:webmcp to declare page features as WebMCP tools: named JavaScript functions with a description and JSON Schema that in-browser agents invoke through document.modelContext. The page states what it can do. WebMCP is a progressive enhancement on an existing site. It is an in-browser API (W3C Web Machine Learning CG draft; Chrome origin trial from Chrome 149), not an Anthropic MCP server.

Choose ak:webmcp for in-browser page tools

Use ak:webmcp when

• You want to add agent-callable tools to a website or web app.
• A form or page action should be invocable by name instead of by scraping.
• You need the imperative registerTool path or the declarative form attributes.
• You need tool annotations, cross-origin exposedTo / Permissions-Policy tools, or WebMCP evals.

Choose another workflow when

• You need a stdio or HTTP MCP server. Use ak:mcp-builder.
• You need to run existing MCP tools. ak:use-mcp is no longer packaged. Use MCP tools already visible in the current session, or ak:agent-browser for browser automation.
• You need generic browser automation. Use ak:agent-browser.

Prepare the browser surface

Confirm the target browser (Chrome 149+ with chrome://flags/#enable-webmcp-testing), HTTPS, and origin isolation. In that browser verify modelContext on document before emitting code. Do not emit navigator.modelContext (deprecated in Chromium 150). Confirm every member against the Skill's API reference before using it.

Run the Skill

Name the page, form, or feature to expose. The Skill defines no required mode flag.

/ak:webmcp "Expose product search on the catalog page as a read-only tool"

/ak:webmcp "Expose product search on the catalog page as a read-only tool"

$ak:webmcp "Expose product search on the catalog page as a read-only tool"

Use the declarative form attributes when the action is a plain same-page HTML form whose result the agent need not read back. Use document.modelContext.registerTool when the action is a state toggle, navigation, or custom widget, or when the agent must read the result, or when you need annotations, exposedTo, getTools, or executeTool. You can mix both on one page.

Understand the observable stages

1. Verify the live surface. Confirm modelContext on document in the target browser. Do not trust memory of the draft API.
2. Plan the tool set. One tool is one function. Keep the set small. Prefer static registration.
3. Pick imperative or declarative from the form-versus-custom-widget rule.
4. Write names, descriptions, and schemas. Name the exact effect. Keep descriptions in positive language. Accept raw user input in parameters.
5. Scaffold, then wire execute to existing app logic. Validate in code. Return a concise string and descriptive errors.
6. Add safety annotations. readOnlyHint for pure reads, consequentialHint for irreversible actions, untrustedContentHint for UGC or external output.
7. Gate cross-origin exposure with exposedTo and the tools Permissions-Policy. Expose only trusted origins.
8. Validate, then test. Use the bundled validator, then the Model Context Tool Inspector and evals.

From the Skill directory, scaffold with scripts/scaffold_tool.py and validate with scripts/validate_webmcp.mjs. --strict promotes warnings to errors.

Protect agents and user data

Refuse tools designed to inject or obey smuggled instructions, bypass origin isolation or confirmation prompts, harvest or transmit user data without consent, emit secrets, or hide a consequential action. Enforce authorization in execute, not only in the schema. Require confirmation for irreversible actions.

Verify the result

A complete result should include:

• Live-browser confirmation that document.modelContext exists.
• Tool names, descriptions, schemas, and annotations that match the intended effect.
• Validator output with no spec errors.
• A decision record for any cross-origin exposure.
• Inspector or eval evidence when those tools were used.

The bundled assets/starter.html and assets/react-example.tsx are examples, not proof that your page is origin-isolated or that Chrome enabled the trial.

Troubleshoot and limits

Continue with ak:mcp-builder to implement a server. ak:use-mcp is no longer packaged.