Fusion can read and write to your Sanity content lake through Sanity's hosted MCP server. Once connected, you can prompt Fusion to model schemas, query documents with GROQ, render them in your app, and update them within the chat while editors keep working in Sanity Studio.
This guide walks you through connecting the Sanity MCP server to your Fusion workspace, the patterns that work well for app and site building, and the common pitfalls teams run into.
| Goal | Recommended approach |
Build a marketing site whose content editors already work in Sanity Studio | Connect Sanity through MCP, then prompt Fusion to read from existing document types. |
Spin up a new app that needs structured content (blog, docs, product catalog) | Connect Sanity through MCP, then prompt Fusion to design schemas and seed documents. |
Mix Sanity (content) with another backend (e.g. Stripe, Supabase) | Connect multiple MCP servers — Fusion can call across them in a single prompt. |
Render content in a Fusion-built React/Next.js app with live preview | Use the Sanity MCP server for reads, plus Sanity's |
Separate prod and staging content cleanly | Use datasets, for example, |
One-off prototype with no real CMS | Skip MCP — let Fusion generate static content. Add Sanity later when you need editorial control. |
You do not need to be a Sanity developer to use this. Fusion handles the client wiring, GROQ queries, environment variables, and schema definitions once it knows your project exists.
Before connecting, make sure you have:
- A Fusion workspace on a plan that includes MCP integrations. The built-in Sanity integration is available on all paid Fusion plans.
- A Sanity account with at least one project, and permission to authorize third-party apps against your organization. The OAuth flow uses your existing Sanity login - no API tokens are needed to connect Fusion to Sanity.
- (Optional) A schema already defined in your Sanity Studio. If you don't have one, Fusion can design and deploy document types for you through the MCP server during the build.
There are two separate access paths:
| Path | What it's for | What you need |
Fusion → Sanity (build time) | Lets Fusion read your schemas, query documents, and create/update content while you're prompting | OAuth only - handled by the Connect button below. No API tokens. (Sessions expire after about 7 days; reconnect when prompted.) |
Your generated app → Sanity (runtime) | Lets the app Fusion built actually fetch content when users visit it | Sanity API tokens - generated per-project in sanity.io/manage → API → Tokens |
When Fusion writes the runtime fetch code, it'll set up the environment variables and tell you which tokens to paste in. The tokens you may need:
- A Viewer token — for reading published content from the dataset. Required for nearly every app.
- A Viewer token with "drafts" permission (or use a public dataset) — for reading draft documents for preview mode. Sanity stores drafts as separate documents with a
drafts.ID prefix, so reading them requires a token that can see them. - An Editor token — for writing content from the running app. Most apps don't need this; Fusion uses its own MCP-authorized access for writes during the build.
You can create these now at sanity.io/manage → your project → API → Tokens, or wait until Fusion prompts you for them — either works.
If you don't have the Integrations tab in your Fusion workspace, your plan may not include it. Contact your Builder.io account team.
Fusion ships with Sanity as a built-in MCP server, so connecting it is a one-click OAuth flow - no URLs, tokens, or scopes to configure manually.
- In Fusion, click the Integrations nav item in the left-hand menu.
- Scroll to Built-in MCP Servers.
- Find the Sanity card and click Connect.
- A Sanity OAuth window opens. Sign in (if needed) and approve the scopes:
- The window closes and the Sanity card now shows Connected, with a Manage button for disconnecting or reconfiguring later.
That's it. Fusion can now reach https://mcp.sanity.io on your behalf for any conversation in this workspace.
Heads up: 7-day sessions. Sanity's OAuth sessions expire after roughly a week. If Fusion suddenly can't reach Sanity, click Manage → Reconnect and re-authorize.
Sanity organizes content into organizations, projects, and datasets. A dataset is an isolated content repository — most teams use them as environments, for example, production and stagingbut they can also separate tenants, regions, or experimental content. Most teams want Fusion to default to one project and a dataset, so Fusion doesn't have to ask every turn.
- Click Manage on the connected Sanity card.
- Pick a Default project and Default dataset from the dropdowns. Both are populated from the projects your Sanity user can access.
- Save.
You can override these per conversation by telling Fusion to "use the staging dataset instead". This causes Fusion to pass that through to subsequent MCP calls in that chat.
From the same Manage menu:
- Reconnect. Re-runs the OAuth flow. Use this if the scopes have changed, your session has expired, or you need to switch to a different Sanity account.
- Disconnect. Removes the integration from this Fusion workspace. Your Sanity data is untouched; Fusion loses access, but nothing in Sanity changes.
Disconnecting does not modify any code Fusion has already written. If your app uses @sanity/client with an API token, that keeps working - the MCP connection is for Fusion's own access during builds.
Once connected, Fusion can call the Sanity MCP server's tools on its own when your prompt needs them. The most useful capabilities, grouped by category:
| Capability | What Fusion can do |
Inspect projects & datasets | List organizations, projects, datasets, and deployed schemas. Use this to ground generated UI in real schemas. |
Read documents (GROQ) | Execute GROQ queries against published or draft documents, including referenced documents and asset URLs. |
Create documents | Seed example content during a build (from JSON or Markdown), or scaffold editorial flows. |
Patch documents | Apply field-level patches. For published documents, the MCP creates or updates the corresponding |
Publish / unpublish / discard drafts | Move documents between draft and published states. |
Deploy schemas & Studio | Define new document types and deploy them. Fusion can even deploy a managed Sanity Studio if you don't already have one. |
Manage releases | Create releases for coordinated, scheduled publishing across multiple documents (Sanity's batched-publish primitive). |
Manage assets & AI media | Generate or transform images directly into asset fields (note: these consume Sanity AI credits). |
Semantic search & docs | Search Sanity documentation, run semantic search over embeddings indices, and surface migration guides. |
CORS & project config | Add CORS origins so the app Fusion builds can call Sanity from the browser without errors. |
Fusion decides which of these to call based on your prompt. You don't invoke them directly. Instead, you describe the outcome — for example, "Show the three most recent blog posts on the homepage". In this case, Fusion writes the GROQ, generates the rendering code, and wires @sanity/client.
About AI credits
A handful of tools, such as create_documents_from_markdown, patch_document_from_markdown, generate_image, transform_image, and create_version (when given an instruction), invoke Sanity's AI inference and consume credits from your Sanity plan. Fusion uses them when they're the natural fit, for example, ingesting a long Markdown article. If you want to avoid using the credits, tell Fusion, "don't use the Markdown ingestion tools — use the JSON ones instead".
Best for marketing teams that already have content modeled in Sanity Studio and want a new site or landing page experience without rebuilding the CMS.
Prompt example:
"Connect to my Sanity project and build a marketing homepage. Use the landingPage document type for hero + features, and the caseStudy document type for the testimonial section. Make it responsive."
What Fusion does behind the scenes:
- Calls
list_workspace_schemasandget_schemato confirmlandingPageandcaseStudyexist and learn their fields - Writes a GROQ query and calls
query_documentsto pull a few documents as live sample content while you iterate visually - Generates a Next.js (or your chosen framework) page that uses
@sanity/clientat runtime, with environment variables it prompts you to fill in.
For efficiency, tell Fusion the exact document type names. If you say "use my pages document type" and you have both page and landingPage, Fusion has to ask you for clarification.
Best when you're starting from a blank Sanity project and want Fusion to design the schema, deploy a Studio, and build the consuming app in one pass.
Prompt example:
"I'm building a recipes app. Design and deploy a Sanity schema (Recipe with title, slug, hero image, ingredients list, steps, prep time), deploy a Studio so editors can manage them, seed 5 example recipes, and build a Next.js app that lists them on a /recipes page with detail routes."
Fusion:
- Calls
deploy_schemato defineRecipewith the fields you described. - Calls
deploy_studioto provision a managed Sanity Studio bound to that schema (production URLs end insanity.studio). - Calls
create_documents_from_jsonfive times with plausible seed data. - Generates the app routes, render code, and
@sanity/clientconfig.
After the build, your editors can open the Studio URL and start editing - they don't see Fusion at all.
Tip: Review the schema Fusion proposes before letting it deploy. A 10-second confirmation up front is cheaper than reshaping fields later - and unlike untyped CMSes, Sanity's schema is enforced by the client.
Best when multiple documents need to go live together, for example, a product launch page, pricing page, and blog post launching on the same day.
Prompt example:
"Create a release called summer-launch-2026 and add versioned drafts of the homepage hero copy, the pricing page, and a new blog post announcing the launch. Schedule them all to publish on June 1."
Fusion:
- Calls
create_releaseto create the release container. - Calls
create_versionto attach each document's draft to that release. - Hands off the actual scheduling to you (you'll set the publish time in Sanity Studio, or Fusion can stage it using the release tools).
Editors can review the entire release together in Studio before it goes out - cleaner than coordinating individual document publishes.
Sanity doesn't have a built-in locale system the way some headless CMSes do. Localization is typically modeled in the schema, for example, with per-field language variants, or per-document, with a language field.
Prompt example:
"My Sanity schema uses internationalized strings via the @sanity/document-internationalization plugin - each landingPage has a language field. Build the homepage so it reads the locale from the URL (/fr or /en) and queries the matching landingPage document."
Tell Fusion which localization pattern your schema uses (field-level, document-level, or a plugin) and it'll write the right GROQ.
Fusion can use multiple MCP servers in one conversation. A typical pattern:
- Sanity - Marketing pages, blog, product copy.
- Stripe - Pricing data and checkout.
- Supabase / Neon - User accounts and per-user state.
Connect each in Settings → Integrations and prompt across them naturally ("Pull pricing tiers from Stripe and the matching feature copy from Sanity's pricingTier document type").
- Be explicit about project and dataset when it matters. Fusion uses your defaults from Manage, but on the first turn of a new conversation it's worth saying "using the
productiondataset of theMarketingproject" to remove ambiguity. - Drafts have a different document ID. Sanity stores drafts as separate documents prefixed with
drafts.. When Fusion patches a published document, it actually creates/updates thedrafts.version - the live document doesn't change until you publish. If you don't see your change on the site, check whether it was published. - GROQ is the query language, not REST. When Fusion generates fetch code, it'll use GROQ via
@sanity/client. If you're familiar with SQL or GraphQL, GROQ is the third option - Fusion handles the syntax, but learning the basics pays off when you read the generated code. - Don't paste API tokens into the chat. The MCP connection handles Fusion's access via OAuth. Runtime tokens for the generated app go into your project's environment variables - Fusion will tell you which ones to set.
- Document type names are case-sensitive. Schema type names are stable identifiers (e.g.
landingPage, notLandingPageorLanding Page). When in doubt, ask Fusion to "list document types in my default project" and reference them by the name it returns. - CORS for browser-side queries. If your generated app calls Sanity from the browser (not just server-side), the dataset needs your app's origin added to its CORS allowlist. Fusion can do this automatically via the
add_cors_origintool - just tell it the deployed URL. - Image transformations are free; AI image generation isn't. Sanity's standard Image API (resizing, cropping, format conversion) is free and Fusion will use it by default. The AI tools (
generate_image,transform_image) consume Sanity AI credits - opt in deliberately. - Revoking access in Sanity. If you revoke the OAuth grant directly in Sanity (sanity.io/manage → your account), Fusion's connection will silently fail on the next call. Reconnect from Manage in Fusion to fix it.
- Multiple Sanity organizations. OAuth scopes Fusion to the Sanity account you signed in with. If you have multiple organizations, sign in with the user that has access to the org you need before clicking Connect.
- Reconnect every ~7 days. Sanity's OAuth sessions don't last forever. If Fusion suddenly can't see your projects, the session expired - Manage → Reconnect fixes it.
"I don't see Sanity under Built-in MCP Servers." Either your plan doesn't include MCP integrations, or the integration is rolling out. Check out Integrations - if you see other built-ins (Contentful, Supabase, Linear) but not Sanity, contact Builder.io support. If you see no built-in servers at all, your plan likely doesn't include the feature.
"The OAuth popup closes immediately or shows an error." The most common cause is a browser blocking third-party cookies for the popup. Try:
- Disabling popup blockers for
app.builder.io. - Allowing third-party cookies for
sanity.ioduring the flow. - Using a non-incognito window.
If it still fails, copy the URL the popup tried to open and share it with support.
"Fusion says it can't find my document type." Three things to check:
- You're in the right project and dataset (open Manage on the Sanity card to confirm defaults).
- The schema type name matches exactly - case sensitive, camelCase by convention.
- The schema is deployed. Sanity supports schemas deployed via Studio, via the CLI, or via the MCP server itself - if it lives only on a developer's laptop in an undeployed
schemas/folder, the MCP can't see it.
Ask Fusion to "list deployed schemas in my default Sanity project" - if it comes back empty, deploy your Studio (or have Fusion call deploy_schema) first.
"Fusion writes to the wrong dataset."
Fusion uses your default dataset unless you override it mid-conversation. Either change the default under Manage, or include the dataset in your prompt: "…in the staging dataset." If you just wrote to the wrong dataset, Sanity's history view lets you inspect and revert recent changes - but discarded drafts can't be restored.
"My changes don't show up on the live site." Sanity separates drafts from published documents. Fusion's patches go to drafts by default - that's the safe behavior. To publish, either:
- Ask Fusion to "publish those changes" (it'll call
publish_documents), or - Publish from Sanity Studio yourself.
If your site is showing stale content even after publishing, your runtime client is probably caching - check whether you're using @sanity/client with useCdn: true (which caches for ~60 seconds) versus useCdn: false (always fresh, lower rate limit).
"My CORS error from the deployed app."
Sanity's API rejects cross-origin requests unless your dataset's CORS allowlist includes the origin. Tell Fusion "add https://my-app.vercel.app as a CORS origin to my Sanity project" and it'll handle it. You can also do this manually at **sanity.io/manage → your project → API → CORS Origins**.
"My editors don't see new schema types Fusion deployed." They will, on next reload of Sanity Studio. If Studio is showing the old schema, force a rebuild - or, if Fusion deployed a managed Studio for you, give it a minute and refresh. The OAuth user (the person who connected Fusion) is the recorded author of the deploy, and they need permission to deploy schemas in that project.
"I want to use the Sanity MCP server from my own MCP client (Claude Desktop, Cursor, etc.), not just Fusion."
That's supported - see Sanity's docs at sanity.io/docs/ai/mcp-server. The same OAuth flow works; you just point your client at https://mcp.sanity.io. There's also a npx sanity@latest mcp configure CLI command that auto-configures common editors using your existing Sanity CLI credentials.
- Sanity MCP server reference - sanity.io/docs/ai/mcp-server - the full list of tools the MCP server exposes (48 at last count), including ones Fusion will reach for on your behalf.
- Fusion integrations overview - builder.io/c/docs/fusion-integrations-for-developers - the broader catalog of MCP servers Fusion supports, plus the custom-server flow for enterprise plans.
- GROQ cheat sheet - sanity.io/docs/groq - worth a skim before your first build so you can read the queries Fusion generates.
- Sanity content modeling guide - Especially useful if your team is new to schema-first CMSes. Sanity enforces structure more strictly than untyped CMSes; solid schemas up front save weeks later.