Introduction

@timbenniks/contentstack-webmcp is a companion package that helps Contentstack customers expose browser-native WebMCP tools for AI agents visiting public websites.

It complements @contentstack/mcp (stdio/HTTP external agents) with an in-browser tool surface built on the WebMCP Draft Community Group spec via document.modelContext.

Design principle

Framework-native first. The core package is vanilla TypeScript with zero React or Next.js dependency. Optional /react and /next adapters are thin convenience layers — not the default integration path.

Problem it solves

Headless Contentstack sites increasingly need to be agent-ready. Today, customers have two imperfect options:

1. Server MCP via @contentstack/mcp — works with Claude Desktop, Cursor, and other external clients, but requires MCP client configuration. Agents connect from outside the browser.

2. Manual WebMCP — hand-write tool definitions, JSON schemas, fetch/proxy logic, feature detection, security constraints, and cleanup. No Contentstack-specific helpers exist.

@timbenniks/contentstack-webmcp provides opinionated, read-only tools for published content consumption through CDA, running either straight from the browser tab or behind a same-origin proxy, with defensive no-op behavior in unsupported browsers.

When to use it

Scenario	Use @timbenniks/contentstack-webmcp	Use @contentstack/mcp
Agent runs in the browser tab	Yes	No
Agent connects from Claude Desktop, Cursor	No	Yes
Expose published content to visitors	Yes	Possible, not the intent
Content management / authoring	No	Yes
Framework	Any (vanilla default)	Server-side only

What you get out of the box

• 4 CDA-backed tools — search, get by URL, get by UID, list content types
• 3 browser context tools — current page, site info, navigate
• Two execution modes — direct (SDK in the tab, no backend) or proxy (delivery token stays server-side)
• Custom extensibility — createCdaClient, customRoutes, registerCustomTools
• Progressive enhancement — zero impact in Safari, Firefox, older Chrome

Reference implementation

Live on developers.contentstack.com.

Next steps

• Getting started — first integration in under 30 minutes
• Architecture — how the layers fit together
• Credentials — where delivery tokens live