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.

The documentation itself is public. How you reach it depends on the server: the local server and the docs-only MCP search it without credentials, while the hosted connector requires sign-in for every tool, including docs search. The account tools only ever see the one store you connected, whether through sign-in (hosted connector) or an API key (local server).

Ways to connect

Hosted connector (Claude, ChatGPT)

https://mcp.weaverse.io/mcp. Nothing to install: add it as a connector and sign in with your Shopify store. Each store approves its own access.

@weaverse/mcp (local)

Runs on your machine via npx with a Content API key. For Cursor, Claude Code, Codex, VS Code and other local MCP clients.

Docs-only MCP

https://docs.weaverse.io/mcp. Documentation search only, with no store access.

Hosted connector for Claude and ChatGPT

The hosted connector runs the same tools as @weaverse/mcp at https://mcp.weaverse.io/mcp. It never uses an API key. Each store signs in and approves access itself, and every request is limited to that store. Every hosted request needs that sign-in, even documentation search; use the docs-only MCP if you want docs without connecting a store.

Edits are live. The hosted connector offers the nine read tools to every connection. The six edit tools appear only if you grant the edit permission (content:write), and delete_pages also needs the delete permission (content:delete). Edits change your live storefront immediately, so grant edit permission only when you want the assistant to make changes. Weaverse is not yet listed in the Claude or ChatGPT app directories, so add the URL yourself as shown below.

Add the connector

Claude: open Customize → Connectors, add a custom connector, and enter https://mcp.weaverse.io/mcp.
ChatGPT: open Plugins, select + → Add custom MCP server, enter a name and https://mcp.weaverse.io/mcp, choose OAuth authentication, accept the risk warning, and select Create as a plugin (per OpenAI’s Connect and test your plugin guide). Workspace policies may restrict custom MCP servers.

You are sent to Weaverse. Sign in with the Shopify account that owns the store. If you are already signed in to Weaverse, you go straight to the approval screen.

Approve access

The approval screen shows the app asking, your store, and where it sends you back. Reading your projects, pages and theme settings is always included. Every other permission the assistant requests is a separate checkbox, off by default, so leave edit permission unchecked for read-only use. Choose Approve or Deny.

Try a read

Ask “Which Weaverse projects does my store have?” The assistant calls list_projects and shows only your store’s projects.

Permissions

Permission	Approval screen	What the connector can do
`content:read`	Always included	Every read tool and docs search.
`content:write`	”Save drafts and edit content” checkbox	`update_page`, `update_theme_settings`, `update_project`, `create_page`, `assign_template_resources`. Page and theme edits go live on the storefront immediately: this connector does not use drafts. `update_project` only renames the project in Weaverse.
`content:delete`	”Delete content” checkbox	Additionally needed for `delete_pages`. If you ask to delete without it, the assistant asks you to approve it.

The connector’s tools never use publishing, project-management or translation permissions. Leave those unchecked if an assistant requests them. Access tokens last one hour and are renewed automatically while the connection is active. If the store uninstalls Weaverse, every connection stops working immediately.

Disconnect

In the assistant, remove or disconnect the Weaverse connector.
In Weaverse, open Dashboard → Account → Connected AI apps and choose Disconnect. Access is revoked on the very next request. To use the connector again, connect and approve again.

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` (local)

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 (local server)

The local 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

Create a Content API key in Weaverse Dashboard → Account → API Keys.

Add it to your MCP config

Put it in the env block as shown above.

Confirm

Ask your agent to call list_projects. It returns the projects the key can access.

Scopes & shop isolation

Account tools map to Content API scopes (content:read for reads, content:write for edits, content:delete for delete_pages). Each key or connection is scoped to a single Weaverse store: requests can only touch that store’s projects, and reaching across stores returns a 403. Revoke keys in Dashboard → Account → API Keys and hosted connections in Dashboard → Account → Connected AI apps.

Available tools

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 reads (hosted connection or `WEAVERSE_API_KEY`)

Tool	Description
`list_projects`	List the projects in your store (cursor-paginated).
`get_project`	Get one project, including its `revision`.
`list_pages`	List page assignments in a project (filter by `type` / `locale`).
`get_page`	Get a page’s content and its `updatedAt`. Defaults to the editable `weaverse` item tree; `format: "portable-text"` is a read-only view.
`get_theme_settings`	Get a project’s own theme settings and their `revision`.
`list_languages`	List a project’s locales.
`get_openapi_spec`	Get the Content API’s OpenAPI document (public reference data).

Live edits (opt-in)

Edit tools appear only when edits are allowed: on the local server with WEAVERSE_ENABLE_LIVE_WRITES=true and a key, and on the hosted connector when you granted the edit permission (content:write). delete_pages is listed with them but also needs the delete permission (content:delete).

Tool	Description
`update_page`	Merge item data, create typed items, relink `children`. Pass `expectedUpdatedAt` from `get_page`. Live immediately.
`update_theme_settings`	Merge top-level theme keys. Pass `expectedRevision` from `get_theme_settings`. Live immediately.
`update_project`	Rename a project (Weaverse metadata only, not storefront content). Pass `expectedUpdatedAt` = `get_project.revision`.
`create_page`	Create a page and its assignment. Live immediately.
`assign_template_resources`	Attach products/collections to an existing shared template page. New routes go live immediately.
`delete_pages`	Soft-delete pages by ids, or by handles + type + locale. Needs `content:delete`. Live immediately.

The edit tools require @weaverse/mcp 4.0.0 or later for the update_project revision check and the required locale on handle deletes. npx -y @weaverse/mcp fetches the latest version.

get_page can also return Portable Text (format: "portable-text"), structured JSON that is easier for an LLM to read. It is read-only: edit with the default weaverse format.

Try it

Once @weaverse/mcp is connected, a read-only prompt is a safe first check:

Use the Weaverse MCP server. List my Weaverse projects. For the first project, list its pages and summarize them by page type and locale. Do not call any write tools.

Open in Cursor

Content writes & safety

Write tools change the live storefront immediately: edits propagate through the same cache-invalidation path as a Studio save. The MCP tools have no draft, preview, publish or restore step and no automatic rollback. Weaverse’s own drafts, publishing and version restore exist in Studio and the Content API, but this connector does not use them. The assistant should confirm each change with you first.

Read first, then write. The three update tools take a baseline from your last read: update_page (get_page.updatedAt), update_theme_settings (get_theme_settings.revision) and update_project (get_project.revision). If someone changed the content since (for example in Studio), the write is rejected with 409 instead of overwriting newer work. Re-read and try again. The hosted connector requires the baseline on these three tools. create_page, assign_template_resources and delete_pages take no baseline; they have their own checks (for example, a duplicate page or a missing content:delete permission is refused).
Send only the keys you mean to change; nested objects are replaced wholesale.
A 500 after a create, delete or assignment may come after the change was saved. Re-read before retrying.

Write scope is deliberately narrow:

Page content — merge item data, create items, relink children (update_page), create pages (create_page), attach resources to a template page (assign_template_resources), and soft-delete pages (delete_pages).
Theme settings — top-level key merges only (update_theme_settings). Weaverse attempts a theme-version snapshot, but this connector cannot restore it.
Project — name only (update_project). This renames the project in Weaverse (project metadata); it does not change storefront content.

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

Local server: confirm WEAVERSE_API_KEY is set in the server’s env block and the key is not revoked in Dashboard → Account → API Keys.
Hosted connector: reconnect. The connection may have been disconnected in Connected AI apps, or the store uninstalled Weaverse.
Docs tools work without a key; only the account tools need one.

An edit is rejected with 409 or asks for a baseline

Someone changed the content since your last read. Re-read with get_page, get_theme_settings or get_project, then apply the change again.
The hosted connector requires expectedUpdatedAt / expectedRevision from that read for update_page, update_theme_settings and update_project.

“Access denied” on a project

The key is scoped to one shop. You can only access that shop’s projects.
Use list_projects to see exactly what the key or connection 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 Integrations

Migration

Weaverse MCP

Weaverse MCP

Ways to connect

Hosted connector (Claude, ChatGPT)

@weaverse/mcp (local)

Docs-only MCP

Hosted connector for Claude and ChatGPT

Permissions

Disconnect

Install & configure `@weaverse/mcp` (local)

Authentication (local server)

Scopes & shop isolation

Available tools

search_weaverse_docs

Account reads (hosted connection or `WEAVERSE_API_KEY`)

Live edits (opt-in)

Try it

Content writes & safety

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

Content API

Shopify Hydrogen Skills

Weaverse CLI

Weaverse SDKs

Troubleshooting

​Weaverse MCP

​Ways to connect

Hosted connector (Claude, ChatGPT)

@weaverse/mcp (local)

Docs-only MCP

​Hosted connector for Claude and ChatGPT

​Permissions

​Disconnect

​Install & configure @weaverse/mcp (local)

​Authentication (local server)

​Scopes & shop isolation

​Available tools

​Docs (no API key; the hosted connector still requires sign-in)

search_weaverse_docs

​Account reads (hosted connection or WEAVERSE_API_KEY)

​Live edits (opt-in)

​Try it

​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

Ways to connect

Hosted connector for Claude and ChatGPT

Permissions

Disconnect

Install & configure `@weaverse/mcp` (local)

Authentication (local server)

Scopes & shop isolation

Available tools

Docs (no API key; the hosted connector still requires sign-in)

Account reads (hosted connection or `WEAVERSE_API_KEY`)

Live edits (opt-in)

Try it

Content writes & safety

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

Related

Troubleshooting