Fusion reads and writes to your Contentful space through Contentful's hosted MCP server. Once connected, prompt Fusion to model content types, query entries, render them in your app, and update them. The data stays in Contentful where your editors already work.
This guide walks you through connecting the Contentful MCP server to your Fusion workspace, the patterns that work well for app and site building, and the things teams typically trip on.
Integrate Builder and Contentful when you want to achieve the following:
- Build a marketing site whose content editors already work in Contentful. Connect Contentful by MCP, then prompt Fusion to read from existing content types.
- Spin up a new app that needs structured content, such as blogs or a product catalog. Connect Contentful by MCP, then prompt Fusion to create content models and seed entries.
- Mix Contentful content with another backend, such as Stripe or Superbase. Connect multiple MCP servers, and Fusion can call across them in a single prompt
- Render content in a Fusion-built React and Next.js app with previews. Use the Contentful MCP server for reads, plus Contentful's standard SDK in the generated code.
- Create a one-off prototype with no real CMS. Skip MCP and let Fusion generate static content. Add Contentful later when you need editorial control.
You do not need to be a Contentful developer to use this. Fusion handles the SDK wiring, environment variables, and query syntax once it knows your space exists.
Before connecting, make sure you have:
- A Fusion workspace on a plan that includes MCP integrations. The built-in Contentful integration is available on all paid Fusion plans.
- A Contentful account with at least one space, and permission to authorize third-party apps against it. The OAuth flow uses your existing Contentful login. No API tokens are needed to connect Fusion to Contentful.
- (Optional) A content model already defined in Contentful. If you don't have one, Fusion can create content types for you through the MCP server during the build.
There are two separate access paths.
This access path lets Fusion read your schema, query entries, and create or update content while you're prompting.
Click Connect to authenticate with OAuth—no API keys required.
This access path lets the app Fusion built fetch content when users visit it.
For this access path, Contentful API keys are required. These keys are generated per-space in Contentful's Settings, under the API keys heading.
When Fusion generates the runtime fetch code, it'll set up the environment variables and tell you which keys to paste. Specifically, you'll want one or more of these ready:
- A Content Delivery API (CDA) token. Used for reading published content. Required for nearly every app.
- A Content Preview API (CPA) token. Used for reading draft content. Needed if your app has a preview mode for editors.
- A Content Management API (CMA) token. Used 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.
Create these now tokens under Settings > API keys in your Contentful space, or wait until Fusion prompts you for them.
Fusion ships with Contentful 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 Contentful card and click Connect.
- A Contentful OAuth window opens. Sign in, if needed, and approve the scopes:
- Read and write Contentful content
- Manage Contentful entries and assets
- Access Contentful space data
- The window closes, and the Contentful card now shows Connected, with a Manage button to disconnect or reconfigure later.
Fusion can now reach https://mcp.contentful.com/mcp on your behalf for any conversation in this workspace.
Contentful organizes content into spaces and environments. Most teams want Fusion to default to one space and environment.
To set a default space and environment within Contentful:
- Click Manage on the connected Contentful card.
- Pick a Default space and Default environment from the dropdowns. Both are populated from the spaces your Contentful user can access.
- Click Save.
Override these per-conversation by prompting with a phrase like, "Use the staging environment instead." Fusion passes that information through to subsequent MCP calls in that chat.
From the Manage menu:
- Reconnect: re-runs the OAuth flow. Use this if the scopes have changed or your session has expired.
- Disconnect: removes the integration from this Fusion workspace. Your Contentful data is untouched. Only Fusion's access is revoked.
Disconnecting does not modify any code Fusion has already written. If your app uses Contentful's standard SDK with an API key, that keeps working. The MCP connection is for Fusion's own access during builds.
Once connected, Fusion can call the Contentful MCP server's tools on its own when your prompt needs them. This provides several useful capabilities.
| Capability | What Fusion can do |
Inspect content models | List your spaces, environments, content types, and fields. Use this to ground generated UI in real schemas. |
Read entries | Query published or draft entries, including linked references and assets. |
Create entries | Seed example content during a build, or scaffold an editorial workflow. |
Update entries | Patch field values, including localized fields, in place. |
Manage content types | Create new content types, add fields, and change validation. Useful when modeling for the first time. |
Manage assets | List uploaded images and files, and upload new assets. |
Fusion decides which of these to call based on your prompt. You don't invoke them directly.
For example, describe the outcome with a prompt like, "Show the three most recent blog posts on the homepage." In response, Fusion calls the right MCP tools, generates the rendering code, and queries the SDK.
Several example of common prompts are included below.
This prompt is best for marketing teams that already have content modeled in Contentful and want a new site or landing page experience without rebuilding the CMS.
Prompt example
"Connect to my Contentful space and build a marketing homepage. Use the landingPage content type for hero and features, and the caseStudy content type for the testimonial section. Make it responsive."
This prompt leads to the following:
- Fusion calls
list_content_typesto confirmlandingPageandcaseStudyexist and learn their fields. - It pulls the first few entries with
get_entriesto use as live sample content while you iterate visually. - It generates a Next.js, or your chosen framework, page that uses Contentful's official SDK at runtime, with environment variables it'll prompt you to fill in.
Tell Fusion the exact content type API IDs you want to use. If you say "use my page's content type" and you have both page and landingPage, Fusion makes a request for more information. Being specific saves tokens.
This type of prompt is best when you're starting from a blank Contentful space and want Fusion to design the content model as it builds the UI.
Prompt example
"I'm building a recipes app. Create the content types in Contentful (Recipe with title, slug, hero image, ingredients list, steps, prep time), seed 5 example recipes, and build a Next.js app that lists them on a /recipes page with detail routes."
This prompt leads to the following:
- A call for
create_content_typeto defineRecipewith the fields you described. - A call to
create_entryfive times with plausible seed data. - It generates the routes, render code, and Contentful SDK config.
After the build, your editors can open Contentful and start editing. These editors do not interact with Fusion at all.
Review the content types Fusion proposes before letting it create them. A 10-second confirmation up front is cheaper than refactoring fields later.
This type of prompt is best when your content is multilingual, and editors expect to keep working in Contentful's locale UI.
Prompt example
"This is a fr-FR + en-US Contentful space. Build the homepage so it reads the locale from the URL (/fr or /en) and pulls the matching translation. Use the landingPage content type."
Fusion reads the locale configuration off your space and generates locale-aware fetches against Contentful's Delivery API.
Fusion can use multiple MCP servers in one conversation. A typical pattern:
- Contentful: used for marketing pages, blog, product copy.
- Stripe: used for pricing data and checkout.
- Supabase / Neon: used for user accounts and per-user state.
Connect each MCP server in Settings > Integrations, and prompt across them naturally. For example, you might say, "Pull pricing tiers from Stripe and the matching feature copy from Contentful's pricingTier content type."
- Be explicit about space and environment when it matters. Fusion uses your defaults from Manage, but on the first turn of a new conversation it's worth instructing Fusion to "use the
masterenvironment of theMarketingSpace" to remove ambiguity. - Drafts vs. published. By default, Fusion reads published entries using Contentful's CDA. If you're previewing unpublished work, tell Fusion to "include draft entries" so that it switches to the CPA and prompts you for a preview token in the generated code.
- Don't paste API keys into the chat. The MCP connection handles Fusion's access via OAuth. Runtime API keys for the generated app go into your project's environment variables - Fusion will tell you which ones to set.
- Content types are case-sensitive. API IDs in Contentful are stable identifiers, for example.
landingPage, notLandingPageorLanding Page. When in doubt, ask Fusion to "list content types in my default Space" and reference them by the API ID it returns. - Asset URLs are stable, but transformations aren't free. Fusion uses Contentful's Images API for resizing by default. If you have a CDN budget concern, ask Fusion to pre-set sensible width and format params, such as
w=1200&fm=webp, on the rendered tags. - Revoking access in Contentful. If you revoke the OAuth grant directly in Contentful (Account → Authorized applications), Fusion's connection silently fails on the next call. Reconnect from Manage in Fusion to fix it.
- Multiple Contentful organizations. OAuth scopes Fusion to the Contentful account you signed in with. If you have multiple orgs, sign in with the user who has access to the org you need, or use Contentful's account switcher before clicking Connect.
"Contentful isn't under Built-in MCP Servers."
Either your plan doesn't include MCP integrations, or the integration is rolling out. Check Settings → Integrations - if you see other built-ins (Sanity, Supabase, Linear) but not Contentful, contact Builder.io Support. If you have 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
contentful.comduring the flow. - Using a non-incognito window.
If it still fails, copy the URL the popup tried to open and share it with support. That URL contains the OAuth client ID Support needs to debug.
"Fusion says it can't find my content type."
Three things to check:
- You're in the right space and environment (open Manage on the Contentful card to confirm defaults).
- The API ID matches exactly - case sensitive, camelCase by convention.
- Your Contentful user has access to that space. The MCP server only sees what your OAuth identity sees.
Ask Fusion to "list content types in my default Contentful space". If it comes back empty, the issue is access, not the prompt.
"Fusion writes to the wrong environment."
Fusion uses your default environment unless you override it mid-conversation. Either change the default under Manage, or include the environment in your prompt: "…in the staging environment." If you just published to the wrong environment, Contentful's bulk actions can roll it back - Fusion can't undo a write after the fact.
"My editors don't get the new content types Fusion created."
The new content types appear on the next page load of the Contentful web app. If the schema is still missing after a refresh, check the Audit log in Contentful. The OAuth user (the person who connected Fusion) is the recorded author, and they need permission to create content types in that space.
"I want to use the Contentful MCP server from my own MCP client (or Claude Desktop, Cursor, and s on), not just Fusion."
See Contentful's Model Context Protocol (MCP) server documentation. The same OAuth flow works; you just point your client at https://mcp.contentful.com/mcp.
- Contentful's Model Context Protocol (MCP) server documentation for the full list of tools the MCP server exposes, including ones Fusion will reach for on your behalf.
- Fusion integrations for the broader catalog of MCP servers Fusion supports, plus the custom-server flow for enterprise plans.
- Contentful Content modeling basics—helpful before your first build, especially if your team is new to headless CMS modeling.