What is WebMCP, and why?

When you ask an AI AGENT or a CLAUDE EXTENSION to carry out a certain task on a page — like filling in a data form or getting data... etc — it relies on taking screenshots or scraping the DOM data, then analysing and processing it, and you may lose all of that with any update to the page! That wastes a lot of time and increases TOKENS consumption, because these tools work by reading the entire page.

With WebMCP available, there's now a direct and explicit communication channel between the AI model and the page: the developer adds their page's tools in document.modelContext, for the Agent to read them directly instead of guessing.

Comparing Server MCP and WebMCP

Unlike traditional MCP, which mainly works inside the Server (Backend) to carry out tasks (Function Calls) when the Agent requests them, its reach stays confined to the server environment. It has no direct access to the current web page the user is browsing.

The comparison does not at all mean that one is better than the other, or that one will replace the other. It's a comparison to clarify the Separation of Concerns.

So why do we still need buttons?

Looking at the future, this might cross your mind: if we can now fully control the page through a protocol like WebMCP, and have the Agent run any JS code easily, why don't we change the UI to be simpler by hiding all the details from the page and showing just one piece of content, one screen / one element... and the only control is a text or voice command to the Agent: show this, search for that... etc.

But many disagree with this vision, for the following reasons:

• 1. If the Agent is missing for any reason, we'll lose control of the page, or it'll be hard to control.
• 2. Having the elements, and their order, helps Screen Readers and serves people of determination.
• 3. Humans learn and explore by seeing the page and its details, so when faced with a blank, silent screen, it'll be hard to discover the features the page offers.
• 4. Sometimes instant interaction with the mouse or the keyboard is way faster than writing a whole text, for some things.
• 5. WebMCP will face a big challenge from organisations and browser companies if it's adopted as a replacement for the traditional UI, because the whole basis of using the browser is the Open Web experience and freedom of movement.

Accessibility and WebMCP

There's a critique, Issue #91, that asks a fundamental question: "Why create a new, separate system for AI when the Accessibility Tree already provides programmatic maps of the page? And why don't we develop the Accessibility Tree instead of inventing WebMCP?"

Summary of the critique

• First: we already have a tree the Browser builds automatically, complete and consistent with the DOM, so we can make use of this feature and connect the Agent to it, instead of building WebMCP with different methods, tools and code — which will become a problem if the page gets updated without updating these tools, unlike the Accessibility Tree, which syncs automatically.
• Second: if we rely on developing the Agent to interact with the Accessibility Tree, people will care about writing ARIA tags, and this will serve two sides at the same time: first, people of determination, and second, the use of the AI Agent. Instead, now we have another way to describe the page, which is WebMCP, working in parallel, with the possibility that one of them falls out of use in the future.
• Third: describing the page's elements and turning them into structured data like this (JSON Schema), writing their inputs and setting their types — that's pure server work, not the UI's job or responsibility.

Answering the critique

To answer the direct question in the critique: yes, there are use cases that neither the Accessibility Tree nor the Backend APIs can handle effectively:

• First: why not rely on the Accessibility Tree
  • Limits of what it sees: because it only expresses the UI (button, div), and it's limited to the values of the element itself (an input value, for example). It doesn't deal with things like a canvas, browser storage, or state inside the code itself (Redux/React).
  • How it gets done: yeah, the Agent can do a certain action through the Accessibility Tree, for example it'll recognise the payment button and click it. But the execution will be in steps: click, wait for the page to come back, look for the next button — and any change in the page makes the sequence even harder. Unlike WebMCP, which calls a ready function like checkoutCart() that runs directly.
  • The cost with big data: in an app like Google Sheets or Figma, for the Agent to reach 500 cells in the table, it'll read 500 DOM elements one by one — slow, and heavy on resources. Unlike WebMCP, which gives a tool like queryGridData(filter) that returns the data structured, straight from the table's memory, without touching the DOM.
• Second: why not rely on the Backend
  • The data isn't on the server in the first place: the data in the page lives in the current session and was never sent to the server, so any API call will work on the server's saved copy, which doesn't have the local edits.
  • And even if you want to get it there: you'll need a constant sync with every new value added in the front: read the live values, serialize, send, and the Agent waits for the response — all that for something the page's own function does in one call.

Best practices

async execute({ date }) {
  const res = await fetch("/api/flights?date=" + date);

  if (res.status === 429) {
    // ❌ return "Error 429";
    return "Too many searches. Wait a minute, or use the search form on the page.";
  }

  return JSON.stringify(await res.json());
}

The code and usage

1. Checking availability

if (document.modelContext) {
  console.log('WebMCP is supported');
} else {
  console.log('WebMCP is not supported in this browser');
}

2. Using registerTool

await document.modelContext.registerTool({
  name: "add-todo",
  description: "Add a new item to the todo list",
  inputSchema: {
    type: "object",
    properties: { text: { type: "string" } }
  },
  execute({ text }) {
    addTodo(text); // calling a function that already exists
    return "Added: " + text; // sent to the Agent
  }
});

3. Annotations

Annotations are added when registering the tool, inside registerTool, and they're hints that help the Agent deal with the tools more accurately.

annotations: {
  readOnlyHint: true,          // only reads, changes nothing
  consequentialHint: false,    // real-world or irreversible, e.g. a payment
  untrustedContentHint: false  // output may contain untrusted content
}

4. Sharing tools with other sites

To make the tool available to another origin, add exposedTo after defining the tool.

{ exposedTo: ["https://trusted-partner.example"] }

And to enable WebMCP inside an iframe from another origin, use allow="tools".

<iframe src="https://widget.example" allow="tools"></iframe>

5. Unregistering the tool

Pass a signal when registering, then use abort() to unregister the tool.

const controller = new AbortController();
await document.modelContext.registerTool(tool, { signal: controller.signal });

controller.abort();

6. The Declarative way: turning a form into a tool

Without JavaScript: you add attributes on an existing <form>.

<form toolname="sign-up" tooldescription="Create a new account">

  <input name="firstName" toolparamdescription="The user's first name">
  <input name="lastName" toolparamdescription="The user's last name">
  <input type="email" name="email" toolparamdescription="The user's email address">
  <button>Sign up</button>

</form>

7. Events

You can tell if the submit event was done by the Agent using event.agentInvoked, and use respondWith() to return a result or reply to it.

form.addEventListener('submit', (e) => {
  if (!e.agentInvoked) return;   // a normal submit by the user
  e.respondWith(searchCars(new FormData(form)));
});

Use toolchange to know when a tool gets registered or cancelled.

document.modelContext.addEventListener("toolchange", async () => {
  const currentTools = await document.modelContext.getTools();
  updateAgentToolRegistry(currentTools);
});

Use toolactivated to know when the Agent fills in the form, before it's sent.

document.modelContext.addEventListener("toolactivated", () => {
  form.scrollIntoView();
});

Use toolcanceled to know when the Agent cancels the call.

document.modelContext.addEventListener("toolcanceled", () => {
  form.reset();
});

Styling with CSS

And for styling while the Agent is working: :tool-form-active for the form, and :tool-submit-active for the submit button in it.

form:tool-form-active { outline: 2px solid orange; }
button:tool-submit-active { opacity: 0.6; }

Sources: WebMCP explainer · Declarative API

Getting ready for (Production)

From the User's side

• Browser availability: Chrome 149 and Edge 150 or newer, and Brave, and also the ChatGPT Desktop app.
  As for Firefox and Safari, they don't support it right now.
• Enabling the WebMCP flag: write chrome://flags/#enable-webmcp-testing in the URL and enable it.
  Note: if the site is registered in the Origin Trial, the tools will work without any flags.
• An Agent that calls the tools: WebMCP only shows the tools, and it needs an Agent inside the browser to use them.
  The easiest way to try it right now is the Model Context Tool Inspector extension, which is a side panel that shows the tools, and a chat to write a certain prompt in.
  And there are other extensions, like WebMCP Inspector.
• From other AI tools: you can use Chrome DevTools for Agents with Claude Code or Gemini CLI or Cursor or Codex.
  Note: the ChatGPT Desktop app supports WebMCP directly.

From the Developer's side

The Origin Trial lets your site's visitors use WebMCP without enabling any flags.

• 1. Register your site's origin (like https://example.com) on the Origin Trial page for Chrome and Edge.
  Every registration will give you a token.
• 2. Add the token in the <head> of every page that has tools:

<meta http-equiv="origin-trial" content="YOUR_TOKEN">

ما هو WebMCP ولماذا ؟

عندما تطلب من AI AGENT أو CLAUDE EXTENSION تنفيذ مهمة معينة في صفحة ما — كـ ملء نموذج بيانات form أو الحصول على بيانات... إلخ — فيتم الاعتماد على التقاط صور الشاشة أو كشط بيانات DOM وتحليل ومعالجة بياناتها، وقد تخسر كل ذلك مع أي تحديث للصفحة! وهو ما يتسبب في ضياع كثير من الوقت وزيادة استهلاك الـ TOKENS نظراً لأن هذه الأدوات تعمل على قراءة الصفحة بأكملها.

مع توافر الـ WebMCP أصبح هناك قناة اتصال مباشرة وصريحة بين نموذج AI والصفحة، حيث يضيف المطور الأدوات (tools) الخاصة بصفحته في document.modelContext ليقرأها الـ Agent مباشرةً بدلاً من التخمين.

مقارنة بين Server MCP و WebMCP

على عكس الـ MCP التقليدي الذي يعمل أساساً داخل الـ Server (Backend) لتنفيذ مهام (Function Calls) عند طلب الـ Agent، تظل حدود عمله محصورة في بيئة الserver. فهو لا يملك وصولاً مباشراً لصفحة الويب الحالية التي يتصفحها المستخدم.

المقارنة لا تعني إطلاقًا أن أحدهما أفضل من الآخر أو أن أحدهما سيغني عن الثاني، بل هي مقارنة لتوضيح فصل المسؤوليات (Separation of Concerns).

ليه لسه محتاجين الأزرار؟

قد يتبادر إلى ذهنك كنظرة مستقبلية: إذا يمكننا الآن التحكم في الصفحة بالكامل عن طريق بروتوكول مثل الـ WebMCP وتنفيذ أي كود JS عن طريق الـ Agent بسهولة، فلماذا لا نعمل على تغيير شكل الـ UI ليكون أبسط عن طريق إخفاء كل التفاصيل من الصفحة وعرض محتوى واحد فقط، شاشة واحدة / عنصر واحد... ويكون المتحكم فقط هو أمر نصي أو صوتي للـ Agent: اعرض كذا، ابحث عن كذا... إلخ.

ولكن يختلف الكثير مع هذا التصور للأسباب التالية:

• 1. إذا غاب الـ Agent لأي سبب، سنفقد أو سيصعب التحكم بالصفحة.
• 2. وجود العناصر وترتيبها يساعد قارئات الشاشة (Screen Reader) وخدمة ذوي الهمم.
• 3. الإنسان بيتعلم وبيستكشف عن طريق رؤيته للصفحة وتفاصيلها، فعند تعرضه لاستخدام شاشة صمّاء سيصعب اكتشاف ما تقدمه الصفحة من مزايا.
• 4. أحياناً التفاعل اللحظي باستخدام الماوس أو لوحة المفاتيح كيبورد بين قوسين بيبقى أسرع بكتير من كتابة نص كامل في بعض الأمور.
• 5. سيواجه الـ WebMCP تحدياً كبيراً من المنظمات وشركات المتصفحات إذا تم اعتماده بديلاً للـ UI التقليدي، لأن أساس استخدام المتصفح هو تجربة الـ Open Web وحرية الحركة.

Accessibility و WebMCP

هناك نقد Issue #91 يتساءل بشكل جوهري: "لماذا ننشئ نظامًا جديدًا ومستقلاً للـ AI طالما أن الـ Accessibility Tree توفر بالفعل خرائط برمجية للصفحة، ولماذا لا نطور شجرة الـ Accessibility بدلاً من اختراع WebMCP؟"

ملخص النقد

• أولاً: لدينا بالفعل شجرة يبنيها الـ Browser تلقائياً، متكاملة ومتسقة مع الـ DOM، فيمكن استغلال هذه الميزة وربط الـ Agent بها بدلاً من بناء WebMCP بطرق وأدوات وأكواد مختلفة، والتي ستصبح مشكلة إذا تم تحديث الصفحة دون تحديث هذه الأدوات، على عكس الـ Accessibility Tree التي تتزامن تلقائياً.
• ثانياً: إذا تم الاعتماد على تطوير الـ Agent للتفاعل مع الـ Accessibility Tree، فسيتم الاهتمام بكتابة أوسام ARIA، وسيخدم هذا طرفين في وقت واحد: أولاً ذوي الهمم، وثانياً استخدام الـ AI Agent. على العكس، الآن لدينا طريقة أخرى لوصف الصفحة وهي الـ WebMCP، اللي بتعمل بشكل متوازٍ، مع احتمال تراجع استخدام أحدهما في المستقبل.
• ثالثاً: وصف عناصر الصفحة وتحويلها إلى بيانات منظمة بهذا الشكل (JSON Schema)، وكتابة مدخلاتها وتحديد أنواعها، ده عمل سيرفر بحت، مش شغل أو مسؤولية الـ UI.

الرد على النقد

للإجابة عن السؤال المباشر في النقد: نعم، هناك حالات استخدام لا تستطيع شجرة الـ Accessibility ولا الـ Backend APIs التعامل معها بفاعلية:

• أولاً: سبب عدم الاعتماد على الـ Accessibility Tree
  • حدود الرؤية: لأنها بتعبّر عن الـ UI فقط (button, div) ومختصرة ع الـ values بتاعت العنصر نفسه (input value مثلاً)، مش بتتعامل مع حاجة زي canvas أو browser storage أو state جوه الكود نفسه (Redux/React).
  • طريقة التنفيذ: اه، ممكن من خلال الـ Accessibility Tree الـ Agent ينفذ عملية معينة، مثال إنه هيتعرف ويضغط ع الـ button الخاص بالـ payment. بس التنفيذ هيكون على شكل خطوات: يدوس، يستنى الصفحة ترجع، يدوّر على الـ button اللي بعده — وأي تغيير في الصفحة بيصعّب التسلسل أكتر. على عكس WebMCP اللي بينده function جاهزة زي checkoutCart() بتتنفّذ بشكل مباشر.
  • التكلفة مع الداتا الكبيرة: في تطبيق زي Google Sheets أو Figma، عشان الـ Agent يوصل لـ 500 خلية في الجدول هيقرا 500 عنصر DOM واحد واحد — بطء واستهلاك عالي للموارد. على عكس WebMCP اللي بيدي أداة زي queryGridData(filter) بترجّع الداتا مهيكلة من ذاكرة الجداول على طول، من غير ما تلمس الـ DOM.
• ثانياً: أسباب عدم الاعتماد على الـ Backend
  • الداتا مش عند السيرفر أصلاً: الداتا في الصفحة عايشة في الـ current session وماتبعتتش للسيرفر، فأي API call هيشتغل على نسخة السيرفر المتسجّلة اللي مفيهاش التعديلات المحلية.
  • وحتى لو عايز توصّلها: هتحتاج sync مستمر مع كل قيمة جديدة بتتضاف في الفرونت: تقرا القيم اللحظية، تـ serialize، تبعت، والـ Agent يستنى الرد — كل ده عشان function الصفحة نفسها بتنفّذها بـ call واحد.

أفضل الممارسات

async execute({ date }) {
  const res = await fetch("/api/flights?date=" + date);

  if (res.status === 429) {
    // ❌ return "Error 429";
    return "Too many searches. Wait a minute, or use the search form on the page.";
  }

  return JSON.stringify(await res.json());
}

الكود والاستخدام

1. التحقق من التوافر

if (document.modelContext) {
  console.log('WebMCP is supported');
} else {
  console.log('WebMCP is not supported in this browser');
}

2. استخدام الـ registerTool

await document.modelContext.registerTool({
  name: "add-todo",
  description: "Add a new item to the todo list",
  inputSchema: {
    type: "object",
    properties: { text: { type: "string" } }
  },
  execute({ text }) {
    addTodo(text); // استدعاء function موجودة مسبقاً
    return "Added: " + text; // يُرسل إلى الـ Agent
  }
});

3. الـ Annotations

التعليقات التوضيحية (Annotations) تُضاف عند تسجيل الأداة داخل registerTool، وهي تلميحات (hints) تساعد الـ Agent على التعامل مع الأدوات بشكل أدق.

annotations: {
  readOnlyHint: true,          // only reads, changes nothing
  consequentialHint: false,    // real-world or irreversible, e.g. a payment
  untrustedContentHint: false  // output may contain untrusted content
}

4. مشاركة الأدوات مع مواقع أخرى

لإتاحة الأداة لـ origin آخر، أضف exposedTo بعد تعريف الأداة.

{ exposedTo: ["https://trusted-partner.example"] }

ولتفعيل WebMCP داخل iframe من origin آخر، استخدم allow="tools".

<iframe src="https://widget.example" allow="tools"></iframe>

5. إلغاء تسجيل الأداة

مرر signal عند التسجيل، ثم استخدم abort() لإلغاء تسجيل الأداة.

const controller = new AbortController();
await document.modelContext.registerTool(tool, { signal: controller.signal });

controller.abort();

6. الطريقة الـ Declarative: تحويل form إلى أداة (tool)

بدون JavaScript: تضيف attributes على <form> موجود.

<form toolname="sign-up" tooldescription="Create a new account">

  <input name="firstName" toolparamdescription="The user's first name">
  <input name="lastName" toolparamdescription="The user's last name">
  <input type="email" name="email" toolparamdescription="The user's email address">
  <button>Sign up</button>

</form>

7. الـ Events

يمكنك التمييز إذا كان الـ submit event قد تم عن طريق الـ Agent باستخدام event.agentInvoked، واستخدام respondWith() لإرجاع نتيجة أو الرد عليه.

form.addEventListener('submit', (e) => {
  if (!e.agentInvoked) return;   // a normal submit by the user
  e.respondWith(searchCars(new FormData(form)));
});

استخدم toolchange لمعرفة متى تسجل أداة أو تلغى.

document.modelContext.addEventListener("toolchange", async () => {
  const currentTools = await document.modelContext.getTools();
  updateAgentToolRegistry(currentTools);
});

استخدم toolactivated لمعرفة متى يملأ الـ Agent الفورم وقبل إرسالها.

document.modelContext.addEventListener("toolactivated", () => {
  form.scrollIntoView();
});

استخدم toolcanceled لمعرفة متى يلغي الـ Agent الاستدعاء.

document.modelContext.addEventListener("toolcanceled", () => {
  form.reset();
});

التنسيق بـ CSS

وللتنسيق أثناء عمل الـ Agent: :tool-form-active للفورم، و :tool-submit-active لزر الإرسال فيها.

form:tool-form-active { outline: 2px solid orange; }
button:tool-submit-active { opacity: 0.6; }

المصادر: WebMCP explainer · Declarative API

الاستعداد للـ (Production)

من ناحية الـ User

• توافر متصفح: Chrome 149 و Edge 150 أو أحدث، و Brave، وكمان تطبيق ChatGPT Desktop.
  أما Firefox و Safari فلا يدعمانه حالياً.
• تفعيل WebMCP flag: اكتب chrome://flags/#enable-webmcp-testing في الـ URL وفعّله.
  ملحوظة: لو الموقع مسجّل في الـ Origin Trial، الأدوات هتشتغل من غير أي flags.
• Agent يستدعي الأدوات: WebMCP بيعرض الأدوات بس، ومحتاج Agent داخل المتصفح يستخدمها.
  أسهل طريقة للتجربة حالياً هي إضافة Model Context Tool Inspector، عبارة عن side panel بيتعرض فيها الـ tools و chat لكتابة برومبت معين.
  وفيه إضافات تانية زي WebMCP Inspector.
• من أدوات الـ AI التانية: تقدر تستخدم Chrome DevTools for Agents مع Claude Code أو Gemini CLI أو Cursor أو Codex.
  ملحوظة: تطبيق ChatGPT Desktop بيدعم WebMCP مباشرةً.

من ناحية الـ Developer

الـ Origin Trial بيخلي زوار موقعك يستخدموا WebMCP من غير ما يفعّلوا أي flags.

• 1. سجّل الـ origin بتاع موقعك (مثل https://example.com) في صفحة الـ Origin Trial لـ Chrome و Edge.
  كل تسجيل هيديك token.
• 2. ضيف الـ token في الـ <head> لكل صفحة فيها tools:

<meta http-equiv="origin-trial" content="YOUR_TOKEN">