Migration Notes: navigator.modelContext and provideContext() to document.modelContext

“WebMCP is currently focused on the imperative document.modelContext.registerTool() API described above, which is what the specification defines.”

— WebMCP README, November 2026¹

If you wrote WebMCP code in the first half of 2026, or you’re reading a tutorial from back then, it probably starts with navigator.modelContext.provideContext({ tools: [...] }). None of that runs in a current browser. This appendix shows what changed, when, and how to port the code, using the same Fjord Table tools in both shapes. Chapter 5 tells the story behind the two big changes. This appendix is the practical checklist, and since this edition it also covers the shorter step from the book’s first edition (October 2026) to today, plus the proposals that could make you port again.

The dates come from the commit history of the specification repository, webmachinelearning/webmcp, read on 14 October 2026 and re-checked on 15 October 2026. I checked the merge times of the key pull requests against GitHub’s own records.² The specification has no changelog section of its own, so the commit log is the record. The “after” code was tested in Chromium 156.0.8078.4 with --enable-features=WebMCPTesting. The listings and their tests are in the book’s demos repository, in appendices/d-migration/, and I re-ran all 20 checks on 2 November 2026: they still pass.

D.1 What changed, and when

Table D.1 — API-shape changes in the WebMCP specification, February to October 2026

Two of these rows break old code outright: 5 March and 27 May. The others change details you’ll meet while porting. The two October rows don’t affect migration from navigator, but they explain what you see in Chrome today (Appendix A, Tables A.7 and A.8). And the table stops in October for a reason. The draft of 27 October 2026 has exactly the same IDL as the 15 October one, so nothing after 8 October changes the API shape (Section D.6).

D.2 Before: the early-2026 shape

Listing D.1 is Fjord Table’s two tools written the way the explainer and early tutorials wrote them, close to the example in the explainer of November 2025.¹² It uses everything that has gone since: the navigator namespace, provideContext() to set the whole tool list in one call, clearContext() to drop it, and a second execute argument (a ModelContextClient) whose requestUserInteraction() asked the browser to let the page talk to the user mid-call.

// BEFORE (navigator.modelContext, early 2026). Does not run in current browsers.// provideContext() replaced the page's whole tool set; clearContext() removed it.if ('modelContext' in navigator) {  navigator.modelContext.provideContext({    tools: [      {        name: 'search_availability',        description: 'Find open tables at Fjord Table for a date, time and party size.',        inputSchema: {          type: 'object',          properties: {            date: { type: 'string', description: 'Visit date, YYYY-MM-DD' },            time: { type: 'string', description: 'Preferred time, 24h HH:MM' },            partySize: { type: 'integer', minimum: 1, maximum: 12 }          },          required: ['date', 'partySize']        },        async execute({ date, time, partySize }) {          const slots = await availability.search({ date, time, partySize });          return { date, partySize, slots: slots.map((s) => s.time) };        }      },      {        name: 'book_table',        description: 'Book a table at Fjord Table. Asks the user to confirm first.',        inputSchema: {          type: 'object',          properties: {            date: { type: 'string' },            time: { type: 'string' },            partySize: { type: 'integer', minimum: 1, maximum: 12 },            name: { type: 'string' }          },          required: ['date', 'time', 'partySize', 'name']        },        // The second argument was a ModelContextClient.        async execute(booking, client) {          const ok = await client.requestUserInteraction(() => confirmBooking(booking));          if (!ok) return { booked: false, reason: 'The user declined.' };          return { booked: true, reference: await bookings.create(booking) };        }      }    ]  });  // Leaving the booking view: drop every tool on the page.  window.addEventListener('pagehide', () => navigator.modelContext.clearContext());}

Listing D.2 is the other early pattern: adding and removing single tools with registerTool() and unregisterTool(name). registerTool() returned nothing then.⁴⁷

// BEFORE (navigator.modelContext, February 2026). Does not run in current browsers.// registerTool() returned nothing, and tools were removed by name.navigator.modelContext.registerTool({  name: 'search_availability',  description: 'Find open tables at Fjord Table for a date, time and party size.',  inputSchema: { type: 'object', properties: { date: { type: 'string' } }, required: ['date'] },  async execute({ date }) {    return { date, slots: (await availability.search({ date })).map((s) => s.time) };  }});// Any script on the page could do this, including to tools it didn't register.navigator.modelContext.unregisterTool('search_availability');

In Chromium 156 neither listing works (tested). 'modelContext' in navigator is false, so Listing D.1’s guard quietly skips everything: no error, and no tools. Listing D.2 has no guard and throws a TypeError on its first line. Guess which failure is the dangerous one? The quiet one. The page keeps working for people, and agents simply find nothing.

D.3 After: the current shape

Listing D.3 is the same two tools for the current draft, dated 27 October 2026.¹³ It is close to Chapter 5’s Listing 5.1, wrapped in a function so the test can call it, and its results follow Chapter 11’s convention: a booking returns status: 'booked', and a guest who says no in the page’s dialog gives status: 'cancelled_by_user'.

// AFTER (document.modelContext, 27 October 2026 draft; Chromium 156).// One registerTool() call per tool, one AbortController per view.export async function registerFjordTools({ availability, bookings, confirmBooking }) {  if (!('modelContext' in document)) return null;   // progressive enhancement  const view = new AbortController();  const options = { signal: view.signal };  await document.modelContext.registerTool({    name: 'search_availability',    description: 'Find open tables at Fjord Table for a date, time and party size.',    inputSchema: {      type: 'object',      properties: {        date: { type: 'string', description: 'Visit date, YYYY-MM-DD' },        time: { type: 'string', description: 'Preferred time, 24h HH:MM' },        partySize: { type: 'integer', minimum: 1, maximum: 12 }      },      required: ['date', 'partySize']    },    annotations: { readOnlyHint: true },    async execute({ date, time, partySize }, { signal }) {      const slots = await availability.search({ date, time, partySize, signal });      return { date, partySize, slots: slots.map((s) => s.time) };    }  }, options);  await document.modelContext.registerTool({    name: 'book_table',    description: 'Book a table at Fjord Table. The user confirms in the page first.',    inputSchema: {      type: 'object',      properties: {        date: { type: 'string' },        time: { type: 'string' },        partySize: { type: 'integer', minimum: 1, maximum: 12 },        name: { type: 'string' }      },      required: ['date', 'time', 'partySize', 'name']    },    annotations: { consequentialHint: true },    // The second argument is now { signal }. Confirmation is the page's own UI.    async execute(booking, { signal }) {      const ok = await confirmBooking(booking, { signal });      if (!ok) return { status: 'cancelled_by_user', message: 'The guest declined in the booking dialog.' };      return { status: 'booked', reference: await bookings.create(booking) };    }  }, options);  // Leaving the booking view: abort() unregisters exactly these two tools.  window.addEventListener('pagehide', () => view.abort(), { once: true });  return view;}

Table D.2 lists the changes one by one.

Table D.2 — Porting map: early-2026 shape to the 27 October 2026 draft

Tested in Chromium 156: both tools register, getTools() returns them with their annotations, search_availability returns its slots through executeTool(), book_table goes through the page’s confirmation (both the yes and the no path), and view.abort() removes both tools and fires toolchange.

Still in fluxasking the user mid-call

requestUserInteraction() was removed on 11 June 2026 because, in the words of the pull request, “this interface and its only method are not fully specified and not implemented yet”. The removal is meant to last until issue #165 and pull request #204 settle a more permanent design.⁸ So Listing D.1’s book_table never worked anywhere as written. Pull request #204, now titled “Replace requestUserInteraction with requestUserInput”, was still open on 2 November 2026 (Section D.6).¹⁵ Until a replacement lands, confirm consequential actions in your own UI, as Listing D.3 does and Chapter 13 explains.

D.4 Keeping the “swap the tool set” pattern

To be fair to provideContext(), it had one genuinely useful property: a single-page app could switch views and replace the whole tool list in one call. It was removed because the same call let any script on the page wipe out tools it didn’t own.³ Chapter 5 tells that story. Listing D.4 keeps the useful half. A tool set owns one AbortController, and replace() aborts it and registers the new tools under a fresh one. In simple words, it can only ever remove its own tools.

// AFTER: the useful half of provideContext(), "swap this view's tools",// without the dangerous half. It can only remove tools it registered itself,// and it registers each set all or nothing.export function createToolSet(modelContext = document.modelContext) {  let current = null;  return {    async replace(tools) {      current?.abort();                        // drop the previous set (ours only)      const controller = new AbortController();      current = controller;      try {        await Promise.all(tools.map((tool) =>          modelContext.registerTool(tool, { signal: controller.signal })));      } catch (err) {        controller.abort();                    // roll back the tools that did register        if (current === controller) current = null;        throw err;      }    },    clear() {      current?.abort();      current = null;    }  };}

Tested in Chromium 156: with a tool registered by other code on the same page, replace([menu_search, opening_hours]) followed by replace([book_table]) leaves exactly book_table and the other code’s tool, and clear() leaves only the other code’s tool. Two tools with the same name in one replace() call reject with InvalidStateError, which provideContext() would have accepted without complaint. That rejection is why replace() has a catch. Since 30 October 2026 Chrome’s best-practices page recommends registering a view’s tools all at once and rolling back the whole batch when one of them fails, so an agent never sees half a tool surface.¹⁶ The first edition’s version of Listing D.4 didn’t roll back: after a failed replace(), the tools that did register stayed. Tested in Chromium 156, the version above leaves no tool of the failed set behind.

D.5 Finding old code paths

A site that ported half its code, or a library that still has a navigator branch, fails quietly. Listing D.5 tells the cases apart, so you can log them.

// AFTER: feature detection that also spots outdated code paths.export function webmcpStatus() {  if ('modelContext' in document) return 'current';           // document.modelContext  if ('modelContext' in navigator) return 'legacy-navigator'; // a pre-May-2026 build  return 'unavailable';}

In Chromium 156 with WebMCPTesting, webmcpStatus() returns 'current' (tested). 'legacy-navigator' should only appear in old builds. A quick search of your codebase for navigator.modelContext, provideContext, clearContext, unregisterTool and requestUserInteraction finds the rest.

D.6 From the first edition to now (October to November 2026)

If you followed the first edition of this book, I have good news: you don’t need to port anything. The draft of 27 October 2026 has the same IDL as the 15 October draft the first edition used, line for line (I compared the two IDL indexes), and every listing in this appendix ran unchanged in the same Chromium 156 build.¹³ What moved in those weeks is around the API, not in it.

Table D.3 — What changed between the first edition and November 2026, and what to do

Still in fluxthe next migration

Four open pull requests would change the API again if they merge: Tool as an interface instead of the RegisteredTool dictionary (#348), outputSchema (#254), requestUserInput() (#204) and an openWorldHint annotation (#355). Only the first one could break existing code, and only code that builds or copies RegisteredTool objects by hand. Appendix A, Section A.9, lists what each would change.²¹ My advice for today is simple: treat what getTools() returns as opaque, pass it back to executeTool() as it is, and return objects from every tool.

D.7 Checklist

1. Replace navigator.modelContext with document.modelContext, and the feature test with 'modelContext' in document.
2. Turn each provideContext({ tools }) into one registerTool(tool, { signal }) per tool, sharing one AbortController per view or component.
3. Replace clearContext() and unregisterTool(name) with abort().
4. await every registerTool() and handle rejections (InvalidStateError, NotAllowedError, SecurityError, see Appendix A, Table A.7).
5. Change execute(input, client) to execute(input, { signal }), and pass the signal to anything long-running.
6. Remove requestUserInteraction(). Confirm in your own UI instead and mark the tool consequentialHint: true.
7. Return objects, not strings or undefined. The spec and Chrome still disagree on both (Section D.6).
8. Pass objects, not JSON strings, to executeTool().
9. Register each view’s tools all or nothing (Listing D.4).
10. Re-test in Chrome with chrome://flags/#enable-webmcp-testing enabled, and again on every new stable version.²²

D.8 Summary

• Two changes break early-2026 code: provideContext() and clearContext() were removed on 5 March 2026, and navigator.modelContext moved to document.modelContext on 27 May 2026.
• In Chromium 156 old code fails quietly: navigator.modelContext doesn’t exist, guarded code registers nothing, and unguarded code throws.
• Register one tool per call and unregister by aborting the signal you passed. A small tool-set helper (Listing D.4) keeps the view-switching convenience of provideContext() without its risk, and now rolls back a failed set.
• The execute callback’s second argument is { signal }. requestUserInteraction() is gone until a new design lands, so confirmation belongs in your page.
• Code written for the book’s first edition needs no porting: the 27 October 2026 draft has the same IDL. Return objects, keep getTools() results opaque, and watch the four open pull requests.