diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3089d8d..a5bbd22 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,12 @@ All notable changes to `webmcp-react` are documented here. The format is based o
   hints in the WebMCP spec. Passing either one to `useMcpTool` used to fail to type-check.
   The polyfill already forwarded annotations as-is, so nothing changes at runtime.
 
+### Deprecated
+
+- **Global `Document.modelContext` type.** Clashes with Google's `webmcp-types`, which
+  declares the same global differently. It'll be removed in 2.0.0. Until then see
+  "TypeScript and webmcp-types" in `docs/api.md`.
+
 ## 1.2.1
 
 ### Added
diff --git a/README.md b/README.md
index cca2c02..c156b6f 100644
--- a/README.md
+++ b/README.md
@@ -219,6 +219,10 @@ useMcpTool({
 });
 ```
 
+### TypeScript
+
+`webmcp-react` already types `document.modelContext`, so theres no need to add Google's `webmcp-types` as well. The two packages declare the same global differently and clash if you install both, see [TypeScript and webmcp-types](./docs/api.md#typescript-and-webmcp-types) for details and a workaround.
+
 ### SSR
 
 The library works with Next.js, Remix, and any server-rendering framework. The build includes a `"use client"` banner, so no extra configuration is needed.
diff --git a/docs/api.md b/docs/api.md
index 72167ff..21a6da7 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -201,3 +201,22 @@ The polyfill fires only `toolchange`. It does not dispatch `toolactivated` or `t
 An already-aborted `AbortSignal` also rejects: `registerTool` rejects with the signal's abort reason and skips registration, matching the WebMCP spec and native Chrome 152+. Validation errors take precedence — the aborted-signal check runs after the checks above.
 
 The hook routes these rejections into `state.error` and fires `onError`, except `AbortError` (lifecycle teardown), which is ignored.
+
+## TypeScript and `webmcp-types`
+
+Heads up: webmcp-react already declares `document.modelContext` globally (`registerTool`, `getTools`, `executeTool`, the events etc), so you don't need Google's [`webmcp-types`](https://github.com/webmachinelearning/webmcp-types) on top of it.
+
+If you do install both, things get a bit messy. webmcp-types declares the same property as `readonly` with its own `WebMCP.ModelContext` type, and TypeScript wants every declaration of a global property to be indentical. With `skipLibCheck` off you'll get TS2687 and TS2717 errors from the two `.d.ts` files. With it on (Vite and Next.js have it on by default) you won't see any errors, TypeScript just quietly picks whichever decleration it sees first.
+
+If you're using the `"types": ["webmcp-types"]` setup from their README, ours wins. Honestly the only reason to want theirs is if you're calling `document.modelContext.registerTool` directly and want handler args inferred from `inputSchema`. If thats you, create a `webmcp-types.d.ts` with `/// <reference types="webmcp-types" />` in it and put it first in `include`:
+
+```json
+{
+  "compilerOptions": { "skipLibCheck": true },
+  "include": ["webmcp-types.d.ts", "src"]
+}
+```
+
+This depends on file order so it's worth double checking if you move files around. Quick way to tell which one you got: `getTools` and `executeTool` are optional in our type but required in theirs.
+
+We're dropping our global declaration in 2.0, so after that the two packages should play nicely together.