Weaverse MCP

The Weaverse MCP server connects AI tools (Cursor, Claude, Codex, and any other Model Context Protocol client) to Weaverse. It does two things:

Docs — search the Weaverse documentation and knowledge base.
Your account — read your own Weaverse projects, pages, theme settings, and locales over the Content API, scoped to your shop.

Docs search is public. The account tools require an API key and only ever see the shop that key belongs to.

Two ways to connect

@weaverse/mcp (recommended)

The canonical server. Runs locally via npx, reads your API key from its config, and exposes both the docs tools and the authenticated account tools. Use this when you want your agent to work with your projects.

Hosted docs MCP

https://docs.weaverse.io/mcp — a zero-install, HTTP-only server that exposes docs search only. Good when all you need is documentation lookup. No account access.

Both surfaces search the same documentation. @weaverse/mcp proxies that same docs search and adds account tools on top, so it is a strict superset of the hosted docs MCP.

Install & configure `@weaverse/mcp`

Add the server to your MCP client. Pass your API key (optional — omit it for docs-only use) via the env block.

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):

{
  "mcpServers": {
    "weaverse": {
      "command": "npx",
      "args": ["-y", "@weaverse/mcp"],
      "env": { "WEAVERSE_API_KEY": "your-key" }
    }
  }
}

Edit the config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "weaverse": {
      "command": "npx",
      "args": ["-y", "@weaverse/mcp"],
      "env": { "WEAVERSE_API_KEY": "your-key" }
    }
  }
}

Restart Claude Desktop.

claude mcp add weaverse \
  --env WEAVERSE_API_KEY=your-key \
  -- npx -y @weaverse/mcp

opencode reads opencode.json (project) or ~/.config/opencode/opencode.json (global) with an mcp block:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "weaverse": {
      "type": "local",
      "command": ["npx", "-y", "@weaverse/mcp"],
      "environment": { "WEAVERSE_API_KEY": "your-key" }
    }
  }
}

Codex CLI uses TOML, not JSON. Add to ~/.codex/config.toml:

[mcp_servers.weaverse]
command = "npx"
args = ["-y", "@weaverse/mcp"]
env = { WEAVERSE_API_KEY = "your-key" }

Add to .vscode/mcp.json (or your user mcp.json). VS Code uses a top-level servers key (not mcpServers):

{
  "servers": {
    "weaverse": {
      "command": "npx",
      "args": ["-y", "@weaverse/mcp"],
      "env": { "WEAVERSE_API_KEY": "your-key" }
    }
  }
}

Leave WEAVERSE_API_KEY out to run docs-only — search_weaverse_docs still works. Existing installs that only search docs keep working unchanged.

Using another MCP-compatible client — pi, Gemini CLI, or anything else that speaks MCP? Point it at npx -y @weaverse/mcp and put WEAVERSE_API_KEY in the server’s environment.

Authentication

The server forwards WEAVERSE_API_KEY to the Content API as Authorization: Bearer <key>. It never validates or stores the token itself — the Content API enforces shop scoping and scopes. An account tool called without a valid, sufficiently-scoped key returns a clear auth error, never data.

Get a key

Today: create a Content API key in Weaverse Dashboard → Settings → API Keys.Coming soon: your agent can obtain a scoped, expiring agent_cli token via the device handshake — the agent starts the flow, you approve it once in Builder, and the agent stores the key.

Add it to your MCP config

Put it in the env block as shown above.

Confirm

Ask your agent to run whoami. It returns the projects the key can access (and its shop id + scopes once the handshake ships).

Scopes & shop isolation

Account tools map to Content API scopes (content:read for the read tools). Each key is scoped to a single Weaverse shop — requests can only touch that shop’s projects, and reaching across shops returns a 403-style error. Tokens are revocable any time from Settings → Connected agents / API keys in Builder.

Available tools

Docs (public — no API key)

search_weaverse_docs

Search the Weaverse knowledge base for features, schema/input settings, SDK hooks, theme settings, and implementation guides. Returns titles, direct links, and content. Also registered as search_docs.Backed by the official Weaverse documentation MCP (hosted by Mintlify) — the knowledge base, ranking, and freshness all live upstream.

Account (requires `WEAVERSE_API_KEY`)

Account tools require @weaverse/mcp v2.2.0 or later; write tools require v2.3.0 or later (the unified server, shipped with this release). Documentation search works on every version. Because npx -y @weaverse/mcp always fetches the latest, a fresh install gets the account tools automatically; pin or upgrade if you installed an older version.

Tool	Description
`whoami`	Identify the token: shop id + scopes (when available) and the projects it can access. Call first.
`list_projects`	List the projects in your shop (cursor-paginated).
`list_pages`	List pages in a project (filter by `type` / `locale`).
`get_page`	Get a page’s content. Defaults to Portable Text; pass `format: "weaverse"` for the raw item tree.
`get_theme_settings`	Get a project’s theme settings (design tokens + config).
`list_languages`	List a project’s locales.
`update_page`	Edit a page: merge `data` into existing items, create new typed items, relink `children`. Goes live immediately.
`delete_pages`	Soft-delete pages by ids or handles + type. Takes effect on the live storefront immediately.
`update_theme_settings`	Merge top-level theme settings keys. Snapshots a restorable theme version first.
`update_project`	Rename a project (`name` is the only writable field).

get_page returns Portable Text by default — structured JSON that is far easier for an LLM to reason over than raw HTML strings.

Content writes & safety

Write tools change the live storefront immediately — edits propagate through the same cache-invalidation path as a Studio save. Read the current value first (get_page, get_theme_settings), send only the keys you mean to change, and remember nested objects are replaced wholesale.

Write scope is deliberately narrow:

Page content — merge item data, create items, relink children (update_page), and soft-delete pages (delete_pages).
Theme settings — top-level key merges only; a restorable theme version is snapshotted before every change (update_theme_settings).
Project — name only (update_project).

Account-level operations are never exposed via MCP — creating or deleting projects, billing, team/members, plan changes, and store linkage stay human-only in Weaverse Builder.

How docs search relates to `docs.weaverse.io/mcp`

https://docs.weaverse.io/mcp is the Mintlify-hosted, docs-only MCP (it resolves to https://weaverse.io/docs/mcp). @weaverse/mcp proxies that exact docs search and layers the account tools on top. Pick the hosted URL for a zero-install docs lookup; pick @weaverse/mcp when you want your agent to work with your projects.

Content API

The REST API the account tools wrap — reads and writes. The MCP is its agent-native front end.

Shopify Hydrogen Skills

Agent skills for building Weaverse + Hydrogen storefronts. After setup, the same key powers the account tools here.

Weaverse CLI

Project setup and theme scaffolding.

Weaverse SDKs

Build custom components for Weaverse Hydrogen themes.

Troubleshooting

Account tools return an authentication error

Confirm WEAVERSE_API_KEY is set in the server’s env block.
Verify the key in Weaverse Dashboard → Settings → API Keys (not revoked).
Docs tools work without a key; only the account tools need one.

“Access denied” on a project

The key is scoped to one shop. You can only access that shop’s projects.
Use list_projects / whoami to see exactly what the key can reach.

Server won't start

Ensure Node.js is installed and npx -y @weaverse/mcp can run.
Restart your AI tool after editing its MCP config.
The server logs a startup line to stderr noting whether account tools are enabled.

No docs results

Be specific and use Weaverse terms (e.g. createSchema, WeaverseRoot, “input settings”).
Docs search requires network access to the hosted documentation MCP.

Overview

Developer Tools

APIs

Hydrogen Themes

Hydrogen Integrations

Migration

Weaverse MCP

Weaverse MCP

Two ways to connect

@weaverse/mcp (recommended)

Hosted docs MCP

Install & configure `@weaverse/mcp`

Authentication

Scopes & shop isolation

Available tools

Docs (public — no API key)

search_weaverse_docs

Account (requires `WEAVERSE_API_KEY`)

Content writes & safety

How docs search relates to `docs.weaverse.io/mcp`

Content API

Shopify Hydrogen Skills

Weaverse CLI

Weaverse SDKs

Troubleshooting

​Weaverse MCP

​Two ways to connect

@weaverse/mcp (recommended)

Hosted docs MCP

​Install & configure @weaverse/mcp

​Authentication

​Scopes & shop isolation

​Available tools

​Docs (public — no API key)

search_weaverse_docs

​Account (requires WEAVERSE_API_KEY)

​Content writes & safety

​How docs search relates to docs.weaverse.io/mcp

​Related

Content API

Shopify Hydrogen Skills

Weaverse CLI

Weaverse SDKs

​Troubleshooting

Weaverse MCP

Two ways to connect

Install & configure `@weaverse/mcp`

Authentication

Scopes & shop isolation

Available tools

Docs (public — no API key)

Account (requires `WEAVERSE_API_KEY`)

Content writes & safety

How docs search relates to `docs.weaverse.io/mcp`

Related

Troubleshooting