Skip to main content

WebMCP

shredly-webmcp bridges your Shredly MCP server to the browser's WebMCP API (document.modelContext). Add one script tag to your site and AI agents browsing the page — ChatGPT, Codex, and others — can discover and call your Shredly tools as native site tools.

When you add or update tools in your Shredly dashboard, they appear on the site within 30 seconds. No redeploy.

Installation​

No build step. Add this to the <head> of your page:

<script type="module">
  import { ShredlyWebMCP } from 'https://cdn.shredly.io/shredly-webmcp.js'
  ShredlyWebMCP.init({ slug: 'your-mcp-slug' })
</script>

npm​

npm install shredly-webmcp
import { ShredlyWebMCP } from 'shredly-webmcp'
ShredlyWebMCP.init({ slug: 'your-mcp-slug' })

Usage​

Public MCP (no user auth)​

If your tools don't require a user token, pass only the slug:

<script type="module">
  import { ShredlyWebMCP } from 'https://cdn.shredly.io/shredly-webmcp.js'
  ShredlyWebMCP.init({ slug: 'your-mcp-slug' })
</script>

With per-user authentication​

Pass a getToken function. It's called fresh on every tool invocation — so it always reflects the current session state, even if the user logs in after the page loads:

<script type="module">
  import { ShredlyWebMCP } from 'https://cdn.shredly.io/shredly-webmcp.js'
  ShredlyWebMCP.init({
    slug: 'your-mcp-slug',
    getToken: () => localStorage.getItem('user_token'),
  })
</script>

getToken can also be async for token refresh flows:

ShredlyWebMCP.init({
  slug: 'your-mcp-slug',
  getToken: async () => {
    const token = localStorage.getItem('token')
    return isExpired(token) ? await refreshToken() : token
  },
})

After the user logs in​

Call refresh() to immediately re-sync tools with the new token rather than waiting for the next poll:

async function onLoginSuccess(token) {
  localStorage.setItem('user_token', token)
  await ShredlyWebMCP.refresh()
}

API reference​

ShredlyWebMCP.init(opts)​

Fetches tool definitions from Shredly, registers them with document.modelContext, and starts polling for changes.

OptionTypeDefaultDescription
slugstringrequiredYour Shredly MCP slug
getToken() => string | Promise<string>—Returns the user's Bearer token at call time. Omit for MCPs that don't require auth.
baseUrlstringhttps://mcp.shredly.ioOverride the Shredly base URL
pollIntervalnumber30000How often to check for new tools (ms). Set to 0 to disable.
onSync({ tools, added, lastSync }) => void—Called after each sync. Useful for updating UI.

ShredlyWebMCP.refresh()​

Manually trigger a tool sync. Useful to call immediately after a user logs in.

ShredlyWebMCP.reconnect(opts)​

Stop polling, clear registered tools, and re-initialize with new options. Use when the user changes their connected MCP or logs into a different account.

ShredlyWebMCP.getTools()​

Returns the array of currently registered tool definitions.

ShredlyWebMCP.executeTool(name, args)​

Invoke a tool by name directly, bypassing document.modelContext. Useful for building your own tool-testing UI.

ShredlyWebMCP.stop()​

Stop polling.

How it works​

  1. On init(), the library fetches your tool definitions from Shredly (tools/list is always public — no auth required).
  2. For each tool, it calls document.modelContext.registerTool() with the tool's schema and an execution handler.
  3. The execution handler calls tools/call on your Shredly MCP, injecting the user's token from getToken() at call time — not at init time.
  4. Every pollInterval ms, the library re-fetches the tool list. New tools are registered automatically; no page refresh needed.

If document.modelContext isn't available yet when tools are fetched (it can initialize asynchronously), registrations are queued and flushed as soon as the API appears.

Requirements​

  • Tools must register during initial page load — not behind a user interaction — for AI agents to discover them. The library handles this automatically when init() is called from a module script.
  • The ChatGPT desktop app companion browser must be used. Server-side browsing by the AI does not inject document.modelContext.
  • tools/list on Shredly requires no authentication, so tools register on every page load regardless of session state.

Source​

The library is open source: github.com/VinnieVendemia/shredly-webmcp