WebMCP Spec Browser
Short explanations of discovery, the manifest convention, tool definitions, security and the W3C draft in-page API.
Input
Last reviewed: 2026-10-01
Agents need a way to find your tools. On this platform we use three simple signals. They are our convention, not part of the W3C draft.
- A manifest file at /.well-known/mcp.json that lists your tools.
- A link tag in your page head that points to it.
- Optionally, the same link as an HTTP Link header.
<link rel="mcp-manifest" href="/.well-known/mcp.json">Link: </.well-known/mcp.json>; rel="mcp-manifest"Agents that run inside the browser can also find tools that your page registers with JavaScript. See the In-page API tab.
The manifest is a JSON file. Required fields: name, description, version (semver, like 1.0.0) and tools (at least one). Optional: author and auth.
{
"name": "Full Test Store",
"description": "Tools for searching products and checking stock.",
"version": "1.2.0",
"author": "Full Test",
"auth": {
"type": "apiKey",
"in": "header",
"name": "X-API-Key"
},
"tools": [
{
"name": "search_products",
"description": "Search the product catalog by keyword. Use this when the user wants to find products. Returns a list of matching products.",
"endpoint": "/api/mcp/search_products",
"method": "POST",
"inputSchema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Search keywords"
},
"limit": {
"type": "integer",
"description": "Maximum results"
}
},
"required": [
"query"
],
"additionalProperties": false
}
},
{
"name": "check_stock",
"description": "Check stock for a product by SKU. Use this before promising delivery. Returns the quantity in stock.",
"endpoint": "/api/mcp/check_stock",
"method": "POST",
"inputSchema": {
"type": "object",
"properties": {
"sku": {
"type": "string",
"description": "Product SKU"
}
},
"required": [
"sku"
],
"additionalProperties": false
}
}
]
}Serve it with Content-Type: application/json. If browser code on other sites must read it, also send Access-Control-Allow-Origin.
Each tool has a name, a description, an endpoint and an inputSchema.
- name: 1 to 128 characters using letters, digits, _ . and -. Must be unique.
- description: say what the tool does, when to use it and what it returns.
- endpoint: a path starting with / or a full https:// URL. Agents send the arguments as JSON.
- method: optional, POST by default.
- inputSchema: a JSON Schema with type "object". Describe every parameter and list the required ones.
{
"name": "search_products",
"description": "Search the product catalog by keyword. Use this when the user wants to find products. Returns a list of matching products.",
"endpoint": "/api/mcp/search_products",
"method": "POST",
"inputSchema": {
"type": "object",
"properties": {
"query": { "type": "string", "description": "Search keywords" }
},
"required": ["query"],
"additionalProperties": false
}
}- Use HTTPS everywhere and redirect http:// to https://.
- Protect tools that change data or show private data. Declare how in the manifest auth block (none, apiKey in a header, or OAuth2 client credentials).
- Never put real keys or secrets inside the manifest.
- Only allow the CORS origins you need. Use * only for public, read-only endpoints.
- Rate limit your tool endpoints.
- Check every input on the server, even when an inputSchema exists.
- For risky actions, ask the user to confirm before the tool runs.
{ "auth": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }The W3C draft is written by the Web Machine Learning Community Group. It lets a page register tools in JavaScript, so an agent in the browser can call them inside the user's current session.
- Current drafts use document.modelContext. Earlier drafts and some builds use navigator.modelContext. Check for both.
- registerTool() takes: name, description, inputSchema, optional annotations (for example readOnlyHint) and an execute function.
- execute runs in your page and returns the result to the agent.
- The draft also describes a declarative option: forms with toolname and tooldescription attributes.
- Draft specs change. Check the official text before you ship.
const mc = document.modelContext || navigator.modelContext;
if (mc && typeof mc.registerTool === "function") {
mc.registerTool({
name: "search_products",
description: "Search the product catalog by keyword. Returns matching products.",
inputSchema: {
type: "object",
properties: { query: { type: "string", description: "Search keywords" } },
required: ["query"]
},
annotations: { readOnlyHint: true },
async execute({ query }) {
const res = await fetch("/api/search?q=" + encodeURIComponent(query));
return { content: [{ type: "text", text: await res.text() }] };
}
});
}<form toolname="search_products" tooldescription="Search the product catalog by keyword">
<input name="q">
</form>Related Utilities tools
About WebMCP Spec Browser
Short explanations of discovery, the manifest convention, tool definitions, security and the W3C draft in-page API.
How to use
- Pick a tab to read about one part of WebMCP.
- Copy the examples into your own project.
- Use the linked tools to build and test each part.
Good to know
This page is reference material. We review it regularly.