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: webmcp3description: 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.4---5
6<essential_principles>
7
8WebMCP 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.
9
10**Two APIs:**
11- **Imperative API** — `window.navigator.modelContext` — register tools via JavaScript
12- **Declarative API** — HTML `toolname`/`tooldescription` attributes on `<form>` elements
13
14**Prerequisites:** Chrome 146.0.7672.0+, `chrome://flags/#enable-webmcp-testing` enabled.
15
16**Core principles that always apply:**
17
181. **Tools must be atomic and composable** — one function per tool, no overlapping tools with nuanced differences. Combine similar tools into one with input parameters.
19
202. **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.
21
223. **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.
23
244. **Update UI before returning** — agents use UI state to verify execution. Ensure execute/submit logic updates visible state before resolving.
25
265. **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."
27
28</essential_principles>
29
30<intake>
31What would you like to do?
32
331. **Set up WebMCP** in a project (initial integration)
342. **Add a tool** using the imperative JavaScript API
353. **Add a tool** using the declarative HTML form API
364. **Debug** WebMCP tools that aren't working
375. **Audit** existing WebMCP implementation for best practices
386. **Test** WebMCP tools
397. Something else
40
41**Wait for response before proceeding.**
42</intake>
43
44<routing>
45| Response | Workflow |
46|----------|----------|
47| 1, "setup", "integrate", "install", "start" | `workflows/setup-webmcp.md` |
48| 2, "imperative", "javascript", "js", "register", "programmatic" | `workflows/add-imperative-tool.md` |
49| 3, "declarative", "html", "form", "annotate" | `workflows/add-declarative-tool.md` |
50| 4, "debug", "fix", "broken", "not working", "error" | `workflows/debug-webmcp.md` |
51| 5, "audit", "review", "check", "best practices" | `workflows/audit-webmcp.md` |
52| 6, "test", "verify", "inspect" | `workflows/test-webmcp.md` |
53| 7, other | Clarify, then select workflow or references |
54
55**After reading the workflow, follow it exactly.**
56</routing>
57
58<reference_index>
59
60All in `references/`:
61
62**APIs:** imperative-api.md, declarative-api.md
63**Design:** tool-design.md
64**Events:** events-and-css.md
65**Quality:** testing.md, anti-patterns.md
66
67</reference_index>
68
69<workflows_index>
70
71All in `workflows/`:
72
73| Workflow | Purpose |
74|----------|---------|
75| setup-webmcp.md | Initial WebMCP integration into a project |
76| add-imperative-tool.md | Register tools via JavaScript API |
77| add-declarative-tool.md | Annotate HTML forms as WebMCP tools |
78| debug-webmcp.md | Diagnose and fix WebMCP issues |
79| audit-webmcp.md | Review implementation against best practices |
80| test-webmcp.md | Test tools with inspector extension and agents |
81
82</workflows_index>
83
84<templates_index>
85
86All in `templates/`:
87
88| Template | Purpose |
89|----------|---------|
90| imperative-tool.md | Scaffolding for JS-registered tools |
91| declarative-form.md | Scaffolding for HTML form-based tools |
92
93</templates_index>
94
95<verification_loop>
96
97After every WebMCP change:
98
991. Open Chrome DevTools console — check for JS errors
1002. Verify `navigator.modelContext` exists (Chrome flag enabled?)
1013. Use Model Context Tool Inspector extension to list registered tools
1024. Manually execute a tool from the inspector to confirm it works
1035. Check that UI updates are visible after tool execution
104
105Report to user:
106- "Tools registered: X imperative, Y declarative"
107- "Tool [name]: executes successfully / returns error [detail]"
108- "UI state: updates correctly after execution / missing update"
109
110</verification_loop>
qdhenry