​

WebMCP Documentation: Agent Instructions

​

What this is

​

Site structure

​

Key files

​

Diataxis framework

​

The four types (never mix on a single page)

• A guided learning experience. The teacher holds responsibility. The learner follows.
• Concrete steps, no choices, no branching. Every step produces a visible result.
• Zero conceptual explanation. “We’re using HTTPS because it’s more secure” is enough. Link to the explanation page for the full story.
• Language: “We will…”, “First, do X. Now, do Y.”, “Notice that…”, “You have built…”

• Directions for a competent user solving a real problem.
• Assumes the reader knows the basics and has a specific goal.
• Can branch (“If you need X, do Y”). Addresses real-world conditions.
• No digression, no explanation, no teaching. “If they’re important, link to them.”
• Language: conditional imperatives. “To do X, run Y.”

• Technical description of the machinery. Austere, factual, structured like the code.
• Consulted while working, not read cover-to-cover.
• Describe and only describe. No teaching, no opinions. Link to how-to guides for usage and explanation pages for the “why”.
• Language: “X does Y.”, “You must use X.”, lists, tables, warnings.

• Discursive treatment that deepens understanding.
• Read after stepping away from work. Discusses why, provides context, weighs alternatives.
• Admits opinion and perspective. Makes connections across topics.
• Language: “The reason for X is…”, “Consider…”, analogies, history, alternatives.

​

Cross-linking between types

• Tutorials → link to explanation pages parenthetically: “(see Security Model for details)”
• How-to → link to explanation with one sentence of context: “For background on transports, see Transports and Bridges.” Link to reference pages on first mention of any package.
• Reference → link to how-to for practical usage, explanation for the “why”
• Explanation → link to other explanation pages for related concepts, reference pages when naming specific APIs

​

Canonical locations for concepts

​

Writing style

​

WebMCP-specific rules

• Second-person (“you”) for instructions
• Lead with the verb in steps: “Install the package”, not “You should install the package”
• No em dashes. Use commas, periods, or parentheses.
• No excessive bold. Bold for terms on first definition only.
• No emoji unless the user requests them.

​

Product names

• “WebMCP” for the standard
• @mcp-b/* for packages
• “MCP-B” only in package scope contexts (npm scope, commit messages)

​

Code examples

• Every example must be real, taken from source code, tests, or package READMEs. Do not invent code.
• Specify language for syntax highlighting
• Add titles to code blocks: "filename.ext"
• Use CodeGroup for multi-framework examples
• Use twoslash for TypeScript/TSX hover type information
• Make long examples (50+ lines) expandable

​

Mintlify format

​

Frontmatter requirements

---
title: "Page Title in Sentence case"
description: "Concise summary for SEO and llms.txt"
---

​

Links

• Internal links: root-relative, no extension: [text](/path/to/page)
• Paths must match entries in docs.json
• New pages must be added to docs.json navigation

​

Headings

​

Component selection

• All code blocks must have a language tag
• Use <Steps> with <Step> children, not <Steps> with ### headings inside
• Do not overuse callouts. One per section at most. If everything is a note, nothing is.
• Do not nest components more than two levels deep

​

Source of truth: what we own vs. what the Chrome team owns

​

What the Chrome team / W3C owns (link to these, don’t re-document)

• When documenting navigator.modelContext API shape (methods, parameters, return types), link to the W3C spec and proposal. Our reference pages should provide a quick-lookup summary, but always include a “See the W3C spec for the authoritative definition” link. Do not maintain a competing full spec. If the upstream spec is more detailed, say so and link.
• When documenting the declarative API (toolname, form attributes, schema synthesis, CSS pseudo-classes, SubmitEvent extensions), link to the Chrome team’s declarative explainer. Show a short example, then link. Do not re-document the full type mapping table or constraint mapping table; those will go stale as Chrome iterates.
• When documenting @mcp-b/* packages, that’s ours. Document fully. But clearly mark what is “WebMCP standard” behavior vs. “MCP-B extension” behavior. Treat registerTool and unregisterTool as the stable standard surface. Do not describe provideContext or clearContext as current WebMCP standard methods. Everything else (registerPrompt, registerResource, listTools, callTool, createMessage, elicitInput) is an MCP-B extension.
• When showing demos or examples of the standard working, prefer linking to the Chrome team’s live demos at googlechromelabs.github.io/webmcp-tools/demos/ rather than recreating them.
• Security model documentation should summarize our approach but link to the upstream security-privacy-considerations.md for the full threat model.
• When mentioning native Chrome support, always link to the Model Context Tool Inspector extension. It’s the Chrome team’s official tool for inspecting WebMCP tools and it’s in the Chrome Web Store.

​

What we own (document fully)

​

Brand

​

Do not

• Skip frontmatter (title and description are required on every .mdx file)
• Use absolute URLs for internal links (use root-relative: /path/to/page)
• Use title case for headings (use sentence case: “Getting started”, not “Getting Started”)
• Write code blocks without a language tag
• Use <Steps> with ### headings inside (use <Step title="..."> children)
• Include untested or invented code examples
• Use placeholder values like “foo” or “bar” in code (use realistic values)
• Reference outdated MiguelsPizza organization links
• Mix Diataxis content types within a single page
• Re-explain a concept that has a canonical page (link to it instead)
• Re-document the W3C standard API surface in detail when the upstream spec is more authoritative. Summarize, then link.
• Blur the line between “WebMCP standard” and “MCP-B extension”. Always clarify which layer a feature belongs to.
• Overuse callouts. One per section at most.
• Use decorative formatting, emoji, or excessive bold

​

Development

npx mintlify dev    # Preview at http://localhost:3000