Browser-in-the-Loop AI Agent SDK
Live Demo • 中文文档 • Integration Guide • 接入指南
OceanMCP is an embeddable AI chat assistant SDK that executes tools inside the user's browser — leveraging the authenticated session, DOM access, and application state that only the frontend has. Instead of giving an LLM server-side API keys, you register lightweight tool functions that run in the browser and let the AI orchestrate them.
- Browser-in-the-Loop — Tools execute in the user's browser context with full access to cookies, DOM, and app state. No server-side API keys needed.
- Skill System — Bundle related tools with Markdown instructions. Skills are loaded on-demand to keep the LLM context window efficient.
- Two Tool Formats — Register tools as
executorfunctions (recommended) orcodestrings. Supports both legacy parameter arrays and JSON Schema definitions. - Read/Write Safety — Read tools execute immediately; write tools show an approval UI before running. Override with
autoApprovefor low-risk mutations. - Custom Tool Rendering — Tools can provide
showRendercallbacks (React nodes or framework-agnosticDOMRenderDescriptor) to display rich UI inline in the chat. - Shadow DOM Isolation — The widget renders inside a Shadow DOM by default, ensuring zero CSS interference with your application.
- Theme Support —
light,dark, andauto(follows OS preference). Reactive — change at runtime without re-mounting. - Session Persistence — Conversations are stored in IndexedDB with namespace isolation. Built-in
/newand/sessionsslash commands. - Subagent Delegation — The main agent can delegate parallel research tasks to autonomous subagents with read-only tool access.
- File Upload — Register an upload handler to enable file attachments in the chat.
- Framework Agnostic — Works with React, Vue, Angular, or vanilla JS. UMD and ESM builds included.
- TypeScript First — Full type definitions ship with the package for both ESM and UMD consumers.
┌─────────────────────────────────────────────────────────────────┐
│ Host Web Application │
│ │
│ ┌──────────────┐ registerSkill() ┌───────────────────────┐ │
│ │ Your App │──────────────────► │ OceanMCP Frontend │ │
│ │ Code │ registerTool() │ SDK │ │
│ │ │◄────────────────── │ │ │
│ │ │ tool execution │ ┌─────────────────┐ │ │
│ └──────────────┘ in browser ctx │ │ Chat Widget │ │ │
│ │ │ (Shadow DOM) │ │ │
│ │ └────────┬────────┘ │ │
│ └───────────┼───────────┘ │
│ │ WebSocket │
└───────────────────────────────────────────────────┼──────────────┘
│
┌───────────▼───────────┐
│ OceanMCP API Server │
│ │
│ ┌──────────────────┐ │
│ │ LLM Provider │ │
│ │ (OpenAI / etc) │ │
│ └──────────────────┘ │
│ ┌──────────────────┐ │
│ │ Skill Discovery │ │
│ └──────────────────┘ │
└────────────────────────┘
<script src="https://cdn.jsdelivr.net/npm/oceanmcp@latest/dist/sdk.umd.js"></script>
<script>
OceanMCPSDK.mount();
</script>import OceanMCPSDK from "oceanmcp";
OceanMCPSDK.registerTool({
id: "getOrderList",
name: "Get Order List",
description: "Fetch orders for the current user",
operationType: "read",
executor: async () => {
const res = await fetch("/api/orders", { credentials: "include" });
return res.json();
},
parameters: [],
});
OceanMCPSDK.mount({ locale: "en-US", theme: "auto" });OceanMCPSDK.registerSkill({
name: "inventory-ops",
description: "Manage product inventory: stock levels, transfers, and audits.",
instructions: `
# Inventory Operations
- Always use \`getStockLevel\` before any mutations.
- Stock levels are per-warehouse.
`,
tools: [
{
id: "getStockLevel",
name: "Get Stock Level",
description: "Get stock for a product in a warehouse",
type: "executor",
operationType: "read",
executor: async (args) =>
fetch(`/api/stock/${args.warehouseId}/${args.productId}`).then((r) =>
r.json()
),
parameters: {
type: "object",
required: ["warehouseId", "productId"],
properties: {
warehouseId: { type: "string", description: "Warehouse ID" },
productId: { type: "string", description: "Product SKU" },
},
},
},
],
});# Install dependencies
bun i
# Start the API server
cd packages/api-server && bun run dev
# Start the frontend SDK dev server (in another terminal)
cd packages/frontend-sdk && bun run devThe demo page will be available at http://localhost:3001 with interactive examples for Form Building, TODO List management, and React Flow diagram editing — all driven by the AI through browser-side tools.
oceanmcp/
packages/
api-server/ # Backend API server (LLM proxy, WebSocket, skill discovery)
frontend-sdk/ # Frontend SDK (chat widget, tool registry, skill system)
shared/ # Shared types and constants
| Document | Description |
|---|---|
| Integration Guide | Full SDK integration guide (English) |
| SDK 接入指南 | Full SDK integration guide (Chinese) |
| Type Reference | Complete TypeScript type definitions |
| API Reference | All SDK public methods |
We welcome contributions! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'feat: add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
With OceanMCP, you get an ocean of MCP tools from a single SDK integration. Every frontend capability becomes an AI-callable tool — fetching URLs, submitting forms, clicking buttons, reading DOM state, navigating pages — anything your browser can do, the AI can orchestrate. One SDK, limitless tools.
MIT © OceanMCP Contributors