Wyjaśnienie WebMCP: dostarczanie narzędzi agentom AI w przeglądarkach zamiast domysłów.

Zapytaj agenta AI o rezerwację lotu na stronie internetowej i zobacz, co się stanie. Otwiera stronę i zaczyna ją badać. Który element to wybieracz daty? Który spadek zawiera destynację? Który przycisk wymaga dwóch kliknięć, ponieważ zakrywa go okno modalne? Czasami agentowi udaje się to zrobić. Czasami kliknie w niewłaściwy element, wypełni pole błahostkami lub zatrzyma się przy płatności, ponieważ układ strony zmienił się po nauczeniu modelu.

W ten sposób działa obecnie większość agentów opartych na przeglądarce. Przeglądają DOM, ustalają funkcję każdego elementu na podstawie jego etykiety i położenia, a następnie symulują kliknięcia i naciśnięcia klawiszy, jakie wykonałby człowiek. Ta technika nazywa się actuation – w demonstracjach wygląda doskonale, ale w praktyce zawodzi. Wystarczy zmienić jedną klasę CSS lub przesunąć przycisk, a agent, który działał poprzednio, przestaje funkcjonować poprawnie.

WebMCP jest odpowiedzią na to. Jeśli znasz Model Context Protocol (MCP) w warstwie backend, idea jest prosta: bierze się koncepcję narzędzi i przenosi ją do przeglądarki, tak aby istniała na stronach, które tworzysz.

Dlaczego samo patrzenie na DOM nie wystarcza

Agenty obecnie dostępują do usług dwiema drogami:

• Integracja z backendem. Usługa rejestruje narzędzia w platformie AI za pośrednictwem serwera MCP, OpenAPI lub jakiejś własnej API, a AI komunikuje się bezpośrednio z serwerem, nie dotykając przeglądarki.
• Aktywacja w przeglądarce. Agent otwiera stronę jak człowiek i próbuje odgadnąć, które elementy należy kliknąć lub wypełnić.

Aktywacja jest kosztowna i łatwa do błędnego wykonania. Każdy krok może zostać błędnie zinterpretowany, szczególnie w złożonych, wielowarstwowych interfejsach takich jak nowoczesne aplikacje jednostronicowe.

WebMCP wprowadza trzecią drogę działania, która nie jest ani integracją z backendem, ani przypadkowym klikaniem. Sam serwis określa, co potrafi robić. Zamiast aby agent zgadywał, co robi przycisk Checkout, programista opisuje, jakie zadania wykonuje ten przycisk, jakie dane są potrzebne oraz co zwraca.

Czym jest WebMCP

WebMCP to proponowany standard internetowy opracowany przez Grupę Społeczności Sztucznej Inteligencji w sieci Web w ramach W3C. Specyfikacja definiuje API w języku JavaScript wraz z adnotacjami dla elementów formularzy HTML, dzięki czemu agent wie, jak korzystać z funkcji strony, bez konieczności zgadywania.

Porównaj to z backendowym MCP. Strona implementująca WebMCP zachowuje się jak serwer MCP, którego narzędzia działają jako skrypty po stronie klienta. Tam, gdzie zwykle trzeba byłoby uruchomić oddzielny serwer w celu udostępnienia funkcji, można zarejestrować tę funkcję bezpośrednio z JavaScriptu już działającego na stronie.

Konstrukcję tę tworzą trzy elementy:

• Odkrycie: standardowy sposób na rejestrację narzędzi takich jak checkout lub search_products przez strony u agenta.
• JSON Schema: wyraźne definicje oczekiwanych danych wejściowych i wyjściowych, które zmniejszają halucynacje i nieporozumienia.
• Stan: wspólny obraz aktualnego kontekstu strony, dzięki czemu agent wie, na czym może teraz działać.

Jeszcze jeden szczegół: narzędzia nadal działają w sposób widoczny na stronie. Gdy agent wywołuje narzędzie add_to_cart, wynik pojawia się w interfejsie użytkownika, zamiast dziać się w tle. To ma znaczenie dla zaufania, ponieważ użytkownicy mogą zobaczyć, co zostało dla nich zrobione, a zaprojektowane przez Ciebie doświadczenie nie jest omijane.

Rejestracja WebMCP na stronie

Dodanie go do istniejącej strony nie oznacza jej przebudowy. Jest to dodatkowy warstwa komunikacji działająca na już istniejącym backendzie. Kroki:

1. Włącz środowisko. Ponieważ standard jest jeszcze tylko proponowany, włącz go ręcznie w celach eksperymentalnych. W Chrome otwórz chrome://flags/#enable-webmcp-testing, ustaw wartość na Enabled i zrestartuj przeglądarkę. Jeśli chcesz coś bliższego wersji produkcyjnej, zarejestruj się do wersji testowej WebMCP origin, która pojawi się w Chrome 149, aby prawdziwi użytkownicy mogli korzystać z tej funkcji bez konieczności edytowania ustawień.

2. Wybierz narzędzia warte przedstawienia. Ten krok łatwo jest niedoceniany. Nie przedstawiaj każdej funkcji tylko dlatego, że możesz to zrobić. Zastanów się, w jakich zadaniach ludzie naprawdę chcieliby pomocy agenta – zazwyczaj są to te o jednym jasnym celu: wyszukiwanie, filtrowanie, wysyłanie formularza, dokonywanie zakupów. Unikaj dziesiątek narzędzi na jednej stronie, ponieważ każde zarejestrowane narzędzie zajmuje miejsce w oknie kontekstowym, a długi menu utrudnia agentowi dokonanie wyboru.

3. Wybierz API imperatywne lub deklaratywne. API imperatywne rejestruje narzędzia za pomocą zwykłego JavaScript poprzez funkcję registerTool i nadaje się do złożonej logiki, takiej jak zarządzanie stanem, nawigacja czy łączenie działań. API deklaratywne umieszcza adnotacje bezpośrednio w standardowym elementzie HTML <form>, dzięki czemu narzędzie jest tworzone automatycznie – co pasuje do prostych przypadków opartych na formularzach. Projekty React i Angular oferują opcje dostosowane do tych frameworków. React dostarcza pakiet usewebmcp, którego hook useWebMCP łączy cykl życia narzędzia z procesem montowania i demontowania komponentu. Angular posiada eksperymentalne wsparcie umożliwiające przekształcanie Signal Forms w narzędzia.

4. Uczyń inputSchema szczegółowym. To decyduje o tym, na jakim poziomie agent rozumie narzędzie. Napisz description w zwykłym, naturalnym języku, a nie w wewnętrznych skrótach, oraz zdefiniuj każdą właściwość wraz z jej typem. W przypadku zamkniętego zbioru wartości użyj enum, aby agent rzadziej wysyłał nieprawidłowe dane.

5. Ustaw annotations tak, aby odzwierciedlały rzeczywiste ryzyko. Każde narzędzie wymaga uczciwej etykiety:

• readOnlyHint: true dla narzędzia, które jedynie odczytuje dane i nic nie zmienia.
• consequentialHint: true dla działania o rzeczywistych skutkach, które powinno najpierw poprosić użytkownika o potwierdzenie.
• untrustedContentHint: true wtedy, gdy wynik zawiera treści od innych użytkowników, takie jak recenzje lub komentarze, które mogą ukrywać instrukcje.

6. Połącz funkcję execute z istniejącym punktem końcowym. Funkcja execute może po prostu wywołać już istniejącą trasę API za pomocą fetch(). Trasa Laravel również zadziała poprawnie. Nie ma oddzielnego backendu WebMCP. Tworzysz most front-endowy do logiki biznesowej, która została już sprawdzona w środowisku produkcyjnym.

7. Przetestuj to. Zainstaluj rozszerzenie Chrome o nazwie Model Context Tool Inspector (Chrome Web Store), załaduj swoją stronę i sprawdź, które narzędzia się rejestrują. Możesz również skontaktować się stamtąd z pracownikiem w celu potwierdzenia, że twoje narzędzie jest wywoływane, a jego schemat jest wyraźnie odczytywalny.

8. Traktuj to jako postępowe ulepszenie. Obsługa przez przeglądarki jest ograniczona, więc zwykłe kliknięcia przycisków muszą nadal działać dla użytkowników, których przeglądarki nie obsługują WebMCP. Dodaje to nową ścieżkę, ale nie zastępuje starej.

Przykład: narzędzie do sprawdzania statusu zamówienia

Weźmy sklep internetowy zbudowany na Laravel z stroną statusu zamówień. Zwykły proces polega na tym, że użytkownik loguje się, otwiera zakładkę „Moje zamówienia”, wybiera zakres dat i przegląda listę zamówień wraz z informacjami o stanie dostawy. Agent korzystający z aktualizacji musiałby znaleźć odpowiedni spadkowy menu i przycisk wysłania, a następnie wyodrębnić tabelę z wyników z surowego HTML, która przestaje działać, gdy tylko zmieni się struktura kodu.

Dzięki WebMCP pojedyncze narzędzie obejmuje już istniejący endpoint:

await document.modelContext.registerTool({
  name: 'get_order_status',
  description: 'Look up orders within a given timeframe. Returns order number, shipping status, and current location.',
  inputSchema: {
    type: 'object',
    properties: {
      timeframe: {
        type: 'string',
        enum: ['today', 'yesterday', 'last_7_days', 'last_30_days', 'last_6_months'],
        description: 'Timeframe for the order lookup.'
      }
    },
    required: ['timeframe']
  },
  annotations: {
    readOnlyHint: true,
    consequentialHint: false,
    untrustedContentHint: false
  },
  execute: async ({ timeframe }) => {
    const response = await fetch(`/api/orders/status?range=${timeframe}`, {
      headers: { 'Accept': 'application/json' }
    });
    const data = await response.json();
    return JSON.stringify(data);
  }
});

Wyróżniają się trzy szczegóły. inputSchema oszczędza agentowi konieczności zgadywania formatu, ponieważ wie, jakie wartości akceptuje timeframe. Adnotacja readOnlyHint: true oznacza, że narzędzie nie ma skutków ubocznych, więc nie jest wymagana potwierdzenie. A execute po prostu wywołuje istniejącą trasę w Laravel, więc nic nie musi być ponownie budowane.

Proces płatności jest bardziej delikatny, ponieważ dochodzi do przekazywania pieniędzy i realizacji zamówienia. Wymaga to innego sygnału:

await document.modelContext.registerTool({
  name: 'checkout_cart',
  description: 'Completes checkout for the currently logged-in user\'s cart.',
  inputSchema: {
    type: 'object',
    properties: {
      paymentMethod: { type: 'string', description: 'Payment method selected by the user' }
    },
    required: ['paymentMethod']
  },
  annotations: {
    readOnlyHint: false,
    consequentialHint: true,
    untrustedContentHint: false
  },
  execute: async ({ paymentMethod }) => {
    const response = await fetch('/api/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ payment_method: paymentMethod })
    });
    return await response.text();
  }
});

Przy użyciu consequentialHint: true przeglądarka lub agent wiedzą, że muszą pokazać okno potwierdzenia przed uruchomieniem. Nawet jeśli agent naciśnie przycisk, ostateczna decyzja pozostaje po stronie użytkownika.

Aby wylistować narzędzia zarejestrowane na stronie:

const tools = await document.modelContext.getTools();
console.log(tools);

A aby uruchomić go ręcznie w celach testowych:

const [tool] = await document.modelContext.getTools();
const result = await document.modelContext.executeTool(tool, '{"timeframe": "last_7_days"}');

Pełna podróż w obie strony

Oto kolejność działań podczas rozmowy z agentem, który używa narzędzia get_order_status.

1. Wpisujesz coś w rodzaju „znajdź moje zamówienia z zeszłego tygodnia” do agenta, który ma otwartą stronę sklepu, używając prostego języka.
2. Agent uruchamia funkcję wyszukiwania, wywołując metodę getTools() na danej stronie.
3. Strona zwraca listę swoich narzędzi wraz z ich specyfikacjami, w tym get_order_status wraz z opisem i formatem danych wejściowych.
4. Agent porównuje twoją prośbę z opisami dostępnych narzędzi. Jasny opis pomaga mu od razu wybrać odpowiednie narzędzie.
5. Agent wywołuje metodę executeTool() z argumentami utworzonymi na podstawie rozmowy, takimi jak {timeframe: 'last_7_days'}.
6. Funkcja execute strony wywołuje ten sam punkt końcowy Laravel za pomocą fetch(), dokładnie tak, jakbyś kliknął przycisk.
7. Backend odpowiada w formacie JSON, a narzędzie przekazuje go z powrotem agentowi.
8. Agent formułuje wynik w języku naturalnym i go pokazuje, przy czym cała operacja pozostaje widoczna w interfejsie strony.

Dlaczego to jest lepsze od tradycyjnego uruchamiania?

• Wymaga mniej kontekstu. Agent czyta zwięzłe schemat, a nie tysiące linii kodu, dzięki czemu odpowiedzi są szybsze i tańsze.
• Wyniki są spójne. Narzędzie wywołuje twoją rzeczywistą funkcję, więc zmiana koloru przycisku lub przesunięcie elementu nie psuje jej działania.
• Ludzie zachowują kontrolę. Działania o wysokim ryzyku oznaczone consequentialHint: true nadal wymagają potwierdzenia, więc agent nie może ich wykonać bez prośby.
• Latwiej jest przeprowadzać audyt. Każda interakcja odbywa się za pośrednictwem specjalnego narzędzia, dzięki czemu można dokładnie zarejestrować, co agent zrobił dla użytkownika, co jest znacznie trudniejsze, gdy chodzi tylko o zwykłe klikanie.

Bezpieczeństwo

Ponieważ narzędzia znajdują się na twoich stronach, bezpieczeństwo jest bliżej powierzchni niż w przypadku backend MCP, który zazwyczaj działa izolowany na własnym serwerze. Specyfikacja zapewnia kilka mechanizmów ochrony:

• Izolacja pochodzenia. WebMCP działa wyłącznie w dokumentach z izolacją pochodzenia. Jeśli strona aktywuje document.domain, na przykład za pomocą nagłówka Origin-Agent-Cluster: ?0, WebMCP przestaje działać.
• Polityka uprawnień. Rejestracja narzędzi jest kontrolowana przez politykę tools, której domyślna wartość to self, więc iframy z innych domen nie mogą rejestrować narzędzi, chyba że zezwalasz na to za pomocą allow="tools".
• Ekspozycja na inne źródła. Aby narzędzie było dostępne z innego źródła, należy dodać to źródło do opcji exposedTo. Nic nie jest automatycznie dostępne.
• Trzy wskazówki dotyczące adnotacji. readOnlyHint, consequentialHint oraz untrustedContentHint to coś więcej niż zwykłe etykiety. Wskazują one, czy agent może uruchomić narzędzie bez potwierdzenia, czy też powinien ostrożnie traktować jego wyniki, ponieważ mogą zawierać niepewne treści, takie jak opinie użytkowników, które mogą stanowić zagrożenie w postaci iniekcji kodu.

Jedna szczerze mówiąca uwaga: izolacja między kartami wciąż się rozwija. Jeśli agent pracuje na dwóch kartach, nie ma mechanizmu zapobiegającego wyciekom wrażliwych danych z jednej karty do drugiej. W przypadku zastosowań wymagających wysokiego poziomu zaufania, takich jak bankowość, warto obserwować ten obszar przed poleganiem na tej funkcji.

Stan wsparcia w przeglądarkach

Na początek 2026 roku jest jeszcze wcześnie:

• Grupa społeczności Web Machine Learning przy W3C oficjalnie zaakceptowała tę specyfikację we wrześniu 2025 roku.
• Chrome posiada wersję testową od numeru 149, a pełne wsparcie w Chrome i Edge ma zostać wdrożone w drugiej połowie 2026 roku.
• Dla eksperymentów lokalnych flaga chrome://flags/#enable-webmcp-testing działa bez konieczności uczestnictwa w próbie.
• Rozszerzenie Model Context Tool Inspector pokazuje, jakie narzędzia rejestruje strona, i może symulować rozmowę z agentem.

Propozycja może jeszcze ulec zmianie, więc nie opieraj na niej funkcji produkcyjnych. Wykorzystuj podejście stopniowego ulepszania. Tam, gdzie przeglądarka obsługuje WebMCP, agenci otrzymują dokładniejsze doświadczenie, a tam, gdzie nie, funkcjonuje standardowy tryb ręczny.

Obecne ograniczenia

• Brak przeglądania bez interfejsu użytkownika. API jest przeznaczone do lokalnych procesów przeglądarki z udziałem osoby, a nie do automatyzacji bez nadzoru.
• Wysokie obciążenie przy złożonych interfejsach. Aplikacja z skomplikowanym zarządzaniem stanem prawdopodobnie będzie wymagała refaktoryzacji, aby narzędzia odzwierciedlały rzeczywisty stan aplikacji.
• Odkrywanie wymaga wizyty. Klienci mogą dowiedzieć się o istnieniu narzędzi na stronie tylko poprzez jej odwiedzenie. Na razie nie ma globalnego indeksu, takiego jak mapa strony, dla tych narzędzi.
• Brak zasobów ani powiadomień. Dwa inne elementy z pełnego MCP jeszcze nie trafiły do WebMCP. Jeśli agent musi czytać dokumenty lub pobierać strukturyzowane dane z innych źródeł, nadal potrzebny jest oddzielny serwer MCP.

Od czego zacząć

WebMCP uzupełnia backend MCP, ale go nie zastępuje. Backend MCP nadal jest odpowiedni dla danych i logiki, które muszą znajdować się na serwerze, natomiast WebMCP nadaje się do warstwy interakcji frontendu: złożonych formularzy, nawigacji wieloetapowej oraz działań powiązanych z aktualnym stanem interfejsu użytkownika.

Bezpieczny sposób wprowadzania zmian:

• Włącz flagę lokalną i zarejestruj jeden prosty narzędzie, najlepiej tylko do odczytu, np. do wyszukiwania produktów.
• Od samego początku prawidłowo używaj annotations. Nie odkładaj użycia readOnlyHint i consequentialHint, ponieważ stanowią one podstawę bezpieczeństwa, która określa, w jakim stopniu można zaufać agencie przy korzystaniu z twojego narzędzia.
• Śledź repozytorium grupy Web Machine Learning Community Group na GitHubie, ponieważ dyskusje społeczności stale kształtują specyfikację.

WebMCP jest daleki od doskonałości, ale kierunek rozwoju jest jasny. Internet otrzymuje wyraźny język do komunikacji z agentami, a także klarowny kontrakt pomiędzy deweloperem a agentem zamiast domysłów opartych na DOM. Dla tych, którzy są przyzwyczajeni do narzędzi i schematów z backend MCP, ta zmiana będzie im znajoma. Kontrakt znajduje się teraz bezpośrednio w przeglądarce.