diff --git a/docs/packages/react-webmcp/overview.mdx b/docs/packages/react-webmcp/overview.mdx
new file mode 100644
index 0000000..c3e1682
--- /dev/null
+++ b/docs/packages/react-webmcp/overview.mdx
@@ -0,0 +1,156 @@
+---
+title: "@mcp-b/react-webmcp Overview"
+description: "React hooks for Model Context Protocol (MCP) - Let AI agents like Claude, ChatGPT, Cursor, and Copilot control your React components"
+---
+
+> React hooks for Model Context Protocol (MCP) - Let AI agents like Claude, ChatGPT, Cursor, and Copilot control your React components
+
+[](https://www.npmjs.com/package/@mcp-b/react-webmcp)
+[](https://www.npmjs.com/package/@mcp-b/react-webmcp)
+[](https://opensource.org/licenses/MIT)
+[](https://www.typescriptlang.org/)
+[](https://reactjs.org/)
+
+**[Full Documentation](https://docs.mcp-b.ai/packages/react-webmcp)** | **[Quick Start](https://docs.mcp-b.ai/quickstart)** | **[AI Framework Integration](https://docs.mcp-b.ai/ai-frameworks)**
+
+**@mcp-b/react-webmcp** provides React hooks that expose your components as AI-callable tools via the Model Context Protocol. Build AI-powered React applications where Claude, ChatGPT, Gemini, Cursor, and Copilot can interact with your app's functionality.
+
+## Why Use @mcp-b/react-webmcp?
+
+| Feature | Benefit |
+| ---------------------------- | ---------------------------------------------------------------------------- |
+| **React-First Design** | Hooks follow React patterns with automatic cleanup and StrictMode support |
+| **Type-Safe with Zod** | Full TypeScript support with Zod schema validation for inputs/outputs |
+| **Two-Way Integration** | Both expose tools TO AI agents AND consume tools FROM MCP servers |
+| **Execution State Tracking** | Built-in loading, success, and error states for UI feedback |
+| **Works with Any AI** | Compatible with Claude, ChatGPT, Gemini, Cursor, Copilot, and any MCP client |
+
+## Installation
+
+```bash
+pnpm add @mcp-b/react-webmcp zod
+```
+
+If you only want strict core WebMCP hooks (without MCP-B extension APIs like prompts/resources/sampling/elicitation), use `usewebmcp` instead.
+
+For client functionality, you'll also need:
+
+```bash
+pnpm add @mcp-b/transports @modelcontextprotocol/sdk
+```
+
+**Prerequisites:** Provider hooks require the `document.modelContext` API. Install `@mcp-b/global` or use a browser that implements the Web Model Context API.
+
+Provider hooks register tools with `document.modelContext.registerTool(tool, { signal })` and abort the controller on unmount. The hooks retain a `navigator.modelContext` fallback for older preview runtimes, but `document.modelContext` is the canonical v3 surface. On Chrome Beta 147 native (which ignores the second arg) cleanup cannot remove the tool. Install `@mcp-b/global` for spec-aligned behavior.
+
+## Quick Start - Provider (Registering Tools)
+
+```tsx
+import { useWebMCP } from '@mcp-b/react-webmcp';
+import { z } from 'zod';
+
+function PostsPage() {
+ const likeTool = useWebMCP({
+ name: 'posts_like',
+ description: 'Like a post by ID. Increments the like count.',
+ inputSchema: {
+ postId: z.string().uuid().describe('The post ID to like'),
+ },
+ annotations: {
+ title: 'Like Post',
+ readOnlyHint: false,
+ idempotentHint: true,
+ },
+ handler: async (input) => {
+ await api.posts.like(input.postId);
+ return { success: true, postId: input.postId };
+ },
+ formatOutput: (result) => `Post ${result.postId} liked successfully!`,
+ });
+
+ return (
+
+ );
+}
+```
+
+## API Overview
+
+### Provider Hooks
+
+| Hook | Description |
+| ----------------------------------------------- | --------------------------------------------------------- |
+| `useWebMCP(config, deps?)` | Register a tool with full control over behavior and state |
+| `useWebMCPContext(name, description, getValue)` | Simplified hook for read-only context exposure |
+
+### Client Hooks
+
+| Hook / Component | Description |
+| ------------------- | --------------------------------------------------------- |
+| `McpClientProvider` | Provider component managing an MCP client connection |
+| `useMcpClient()` | Access client, tools, connection status, and capabilities |
+
+## Zod Version Compatibility
+
+This package supports **Zod 3.25.76+** (3.x only).
+
+## Documentation
+
+For full API reference, output schemas, memoization patterns, migration guide, best practices, and complete examples, see the [React WebMCP Guide](../../docs/react-webmcp-guide.md).
+
+## Related Packages
+
+- [`@mcp-b/global`](https://docs.mcp-b.ai/packages/global) - W3C Web Model Context API polyfill (required for provider hooks)
+- [`@mcp-b/transports`](https://docs.mcp-b.ai/packages/transports) - Browser-specific MCP transports
+- [`@mcp-b/chrome-devtools-mcp`](https://docs.mcp-b.ai/packages/chrome-devtools-mcp) - Connect desktop AI agents to browser tools
+- [`usewebmcp`](../usewebmcp) - React hooks for strict core WebMCP API only
+
+## Resources
+
+- [WebMCP Documentation](https://docs.mcp-b.ai)
+- [Model Context Protocol Spec](https://modelcontextprotocol.io)
+
+## License
+
+MIT - see [LICENSE](../../LICENSE) for details
diff --git a/packages/react-webmcp/overview.mdx b/packages/react-webmcp/overview.mdx
index a3ed282..2c7ece9 100644
--- a/packages/react-webmcp/overview.mdx
+++ b/packages/react-webmcp/overview.mdx
@@ -1,11 +1,9 @@
---
-title: "@mcp-b/react-webmcp overview"
-description: "When to use the full React integration package, how it differs from usewebmcp, and which runtime stack it expects."
-keywords: ["@mcp-b/react-webmcp", "overview", "react", "MCP-B", "useWebMCP", "McpClientProvider"]
-icon: "react"
+title: "@mcp-b/react-webmcp"
+description: "React hooks for Model Context Protocol (MCP) - Let AI agents like Claude, ChatGPT, Cursor, and Copilot control your React components"
---
-`@mcp-b/react-webmcp` is the full React surface for MCP-B. It covers tool registration, prompt and resource hooks, sampling and elicitation helpers, and client/provider APIs for consuming MCP servers from a React tree.
+> React hooks for Model Context Protocol (MCP) - Let AI agents like Claude, ChatGPT, Cursor, and Copilot control your React components
## Version
@@ -17,35 +15,148 @@ Current release: **v3.0.0** — aligned with the WebMCP v3 document-first API. P
- You want Zod v3 object-map support and Standard Schema v1 (e.g., Zod v4 `~standard`) in hook configuration.
- You need client/provider hooks (`McpClientProvider`, `useMcpClient`) in addition to browser-exposed tools.
-## When not to use this package
+**@mcp-b/react-webmcp** provides React hooks that expose your components as AI-callable tools via the Model Context Protocol. Build AI-powered React applications where Claude, ChatGPT, Gemini, Cursor, and Copilot can interact with your app's functionality.
- You only need strict-core `registerTool` behavior. Use [`usewebmcp`](/packages/usewebmcp/overview).
- You are not using a BrowserMcpServer-based runtime. Install [`@mcp-b/global`](/packages/global/overview) first.
-## Where it sits in the package graph
+| Feature | Benefit |
+| ---------------------------- | ---------------------------------------------------------------------------- |
+| **React-First Design** | Hooks follow React patterns with automatic cleanup and StrictMode support |
+| **Type-Safe with Zod** | Full TypeScript support with Zod schema validation for inputs/outputs |
+| **Two-Way Integration** | Both expose tools TO AI agents AND consume tools FROM MCP servers |
+| **Execution State Tracking** | Built-in loading, success, and error states for UI feedback |
+| **Works with Any AI** | Compatible with Claude, ChatGPT, Gemini, Cursor, Copilot, and any MCP client |
This package sits above the full runtime stack. It expects `document.modelContext` to come from a browser-native implementation or from the MCP-B runtime that wraps the strict core with `BrowserMcpServer`.
React peer dependency: `^17.0.0 || ^18.0.0 || ^19.0.0`.
Zod peer dependency (optional): `^3.25 || ^4.0`.
-## First step
-
-Initialize the runtime with [`@mcp-b/global`](/packages/global/overview), then add the hook or provider that matches your React use case. The [reference page](/packages/react-webmcp/reference) covers tool hooks, prompt/resource hooks, and client/provider APIs.
-
-## Related pages
-
-
-
- Hook APIs, provider APIs, Zod support, and return types.
-
-
- Guided tutorial for registering a React tool.
-
-
- Apply the full MCP-B React surface.
-
-
- Decide whether the full React surface is necessary.
-
-
+```bash
+pnpm add @mcp-b/react-webmcp zod
+```
+
+If you only want strict core WebMCP hooks (without MCP-B extension APIs like prompts/resources/sampling/elicitation), use `usewebmcp` instead.
+
+For client functionality, you'll also need:
+
+```bash
+pnpm add @mcp-b/transports @modelcontextprotocol/sdk
+```
+
+**Prerequisites:** Provider hooks require the `document.modelContext` API. Install `@mcp-b/global` or use a browser that implements the Web Model Context API.
+
+Provider hooks register tools with `document.modelContext.registerTool(tool, { signal })` and abort the controller on unmount. The hooks retain a `navigator.modelContext` fallback for older preview runtimes, but `document.modelContext` is the canonical v3 surface. On Chrome Beta 147 native (which ignores the second arg) cleanup cannot remove the tool. Install `@mcp-b/global` for spec-aligned behavior.
+
+## Quick Start - Provider (Registering Tools)
+
+```tsx
+import { useWebMCP } from '@mcp-b/react-webmcp';
+import { z } from 'zod';
+
+function PostsPage() {
+ const likeTool = useWebMCP({
+ name: 'posts_like',
+ description: 'Like a post by ID. Increments the like count.',
+ inputSchema: {
+ postId: z.string().uuid().describe('The post ID to like'),
+ },
+ annotations: {
+ title: 'Like Post',
+ readOnlyHint: false,
+ idempotentHint: true,
+ },
+ handler: async (input) => {
+ await api.posts.like(input.postId);
+ return { success: true, postId: input.postId };
+ },
+ formatOutput: (result) => `Post ${result.postId} liked successfully!`,
+ });
+
+ return (
+