WebMCP is a browser-native standard that exposes structured tools for AI agents on websites. Instead of screen-scraping, agents interact through typed JavaScript APIs and HTML annotations.
Two APIs:
- Imperative API —
window.navigator.modelContext — register tools via JavaScript
- Declarative API — HTML
toolname/tooldescription attributes on <form> elements
Prerequisites: Chrome 146.0.7672.0+, chrome://flags/#enable-webmcp-testing enabled.
Core principles that always apply:
Tools must be atomic and composable — one function per tool, no overlapping tools with nuanced differences. Combine similar tools into one with input parameters.
Accept raw user input — tools should accept natural strings (e.g., "11:00") not computed values (e.g., minutes-from-midnight). Minimize cognitive computing for the model.
Validate in code, not schema — schema constraints are helpful but not guaranteed. Validate within execute functions and return descriptive errors so agents can self-correct.
Update UI before returning — agents use UI state to verify execution. Ensure execute/submit logic updates visible state before resolving.
Positive, verb-first descriptions — describe what the tool does and when to use it. Avoid negations. "Creates a calendar event for a specific date" not "Do not use for weather."
- Set up WebMCP in a project (initial integration)
- Add a tool using the imperative JavaScript API
- Add a tool using the declarative HTML form API
- Debug WebMCP tools that aren't working
- Audit existing WebMCP implementation for best practices
- Test WebMCP tools
- Something else
Wait for response before proceeding.
After reading the workflow, follow it exactly.
All in references/:
APIs: imperative-api.md, declarative-api.md
Design: tool-design.md
Events: events-and-css.md
Quality: testing.md, anti-patterns.md
All in workflows/:
| Workflow |
Purpose |
| setup-webmcp.md |
Initial WebMCP integration into a project |
| add-imperative-tool.md |
Register tools via JavaScript API |
| add-declarative-tool.md |
Annotate HTML forms as WebMCP tools |
| debug-webmcp.md |
Diagnose and fix WebMCP issues |
| audit-webmcp.md |
Review implementation against best practices |
| test-webmcp.md |
Test tools with inspector extension and agents |
All in templates/:
| Template |
Purpose |
| imperative-tool.md |
Scaffolding for JS-registered tools |
| declarative-form.md |
Scaffolding for HTML form-based tools |
After every WebMCP change:
- Open Chrome DevTools console — check for JS errors
- Verify
navigator.modelContext exists (Chrome flag enabled?)
- Use Model Context Tool Inspector extension to list registered tools
- Manually execute a tool from the inspector to confirm it works
- Check that UI updates are visible after tool execution
Report to user:
- "Tools registered: X imperative, Y declarative"
- "Tool [name]: executes successfully / returns error [detail]"
- "UI state: updates correctly after execution / missing update"
1---
2name: webmcp
3description: Implement WebMCP in web projects — add browser-native structured tools for AI agents using imperative JS or declarative HTML APIs. Full lifecycle from setup through testing and optimization.
4metadata:
5 source: https://skillmd.com/skills/qdhenry/webmcp
6---
7
8<essential_principles>
9
10WebMCP is a browser-native standard that exposes structured tools for AI agents on websites. Instead of screen-scraping, agents interact through typed JavaScript APIs and HTML annotations.
11
12**Two APIs:**
13- **Imperative API** — `window.navigator.modelContext` — register tools via JavaScript
14- **Declarative API** — HTML `toolname`/`tooldescription` attributes on `<form>` elements
15
16**Prerequisites:** Chrome 146.0.7672.0+, `chrome://flags/#enable-webmcp-testing` enabled.
17
18**Core principles that always apply:**
19
201. **Tools must be atomic and composable** — one function per tool, no overlapping tools with nuanced differences. Combine similar tools into one with input parameters.
21
222. **Accept raw user input** — tools should accept natural strings (e.g., "11:00") not computed values (e.g., minutes-from-midnight). Minimize cognitive computing for the model.
23
243. **Validate in code, not schema** — schema constraints are helpful but not guaranteed. Validate within execute functions and return descriptive errors so agents can self-correct.
25
264. **Update UI before returning** — agents use UI state to verify execution. Ensure execute/submit logic updates visible state before resolving.
27
285. **Positive, verb-first descriptions** — describe what the tool does and when to use it. Avoid negations. "Creates a calendar event for a specific date" not "Do not use for weather."
29
30</essential_principles>
31
32<intake>
33What would you like to do?
34
351. **Set up WebMCP** in a project (initial integration)
362. **Add a tool** using the imperative JavaScript API
373. **Add a tool** using the declarative HTML form API
384. **Debug** WebMCP tools that aren't working
395. **Audit** existing WebMCP implementation for best practices
406. **Test** WebMCP tools
417. Something else
42
43**Wait for response before proceeding.**
44</intake>
45
46<routing>
47| Response | Workflow |
48|----------|----------|
49| 1, "setup", "integrate", "install", "start" | `workflows/setup-webmcp.md` |
50| 2, "imperative", "javascript", "js", "register", "programmatic" | `workflows/add-imperative-tool.md` |
51| 3, "declarative", "html", "form", "annotate" | `workflows/add-declarative-tool.md` |
52| 4, "debug", "fix", "broken", "not working", "error" | `workflows/debug-webmcp.md` |
53| 5, "audit", "review", "check", "best practices" | `workflows/audit-webmcp.md` |
54| 6, "test", "verify", "inspect" | `workflows/test-webmcp.md` |
55| 7, other | Clarify, then select workflow or references |
56
57**After reading the workflow, follow it exactly.**
58</routing>
59
60<reference_index>
61
62All in `references/`:
63
64**APIs:** imperative-api.md, declarative-api.md
65**Design:** tool-design.md
66**Events:** events-and-css.md
67**Quality:** testing.md, anti-patterns.md
68
69</reference_index>
70
71<workflows_index>
72
73All in `workflows/`:
74
75| Workflow | Purpose |
76|----------|---------|
77| setup-webmcp.md | Initial WebMCP integration into a project |
78| add-imperative-tool.md | Register tools via JavaScript API |
79| add-declarative-tool.md | Annotate HTML forms as WebMCP tools |
80| debug-webmcp.md | Diagnose and fix WebMCP issues |
81| audit-webmcp.md | Review implementation against best practices |
82| test-webmcp.md | Test tools with inspector extension and agents |
83
84</workflows_index>
85
86<templates_index>
87
88All in `templates/`:
89
90| Template | Purpose |
91|----------|---------|
92| imperative-tool.md | Scaffolding for JS-registered tools |
93| declarative-form.md | Scaffolding for HTML form-based tools |
94
95</templates_index>
96
97<verification_loop>
98
99After every WebMCP change:
100
1011. Open Chrome DevTools console — check for JS errors
1022. Verify `navigator.modelContext` exists (Chrome flag enabled?)
1033. Use Model Context Tool Inspector extension to list registered tools
1044. Manually execute a tool from the inspector to confirm it works
1055. Check that UI updates are visible after tool execution
106
107Report to user:
108- "Tools registered: X imperative, Y declarative"
109- "Tool [name]: executes successfully / returns error [detail]"
110- "UI state: updates correctly after execution / missing update"
111
112</verification_loop>