Connect to Contentful

Code reads and writes to your Contentful space through Contentful's hosted MCP server. Once connected, prompt Builder Code 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 Builder Code workspace, the patterns that work well for app and site building, and the things teams typically trip on.

When to use Builder Code with Contentful

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 Builder Code 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 Builder Code to create content models and seed entries.
Mix Contentful content with another backend, such as Stripe or Supabase. Connect multiple MCP servers, and Builder Code can call across them in a single prompt
Render content in a Builder Code-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 Builder Code generate static content. Add Contentful later when you need editorial control.

You do not need to be a Contentful developer to use this. Builder Code handles the SDK wiring, environment variables, and query syntax once it knows your space exists.

Prerequisites

Before connecting, make sure you have:

A Builder Code workspace on a plan that includes MCP integrations. The built-in Contentful integration is available on all paid Builder Code 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 Builder Code to Contentful.
(Optional) A content model already defined in Contentful. If you don't have one, Builder Code can create content types for you through the MCP server during the build.

Access paths

There are two separate access paths.

1. Builder Code to Contentful

This access path lets Builder Code read your schema, query entries, and create or update content while you're prompting.

Click Connect to authenticate with OAuth—no API keys required.

2. Your generated app to Contentful

This access path lets the app Builder Code 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.

Contentful API keys

When Builder Code 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; Builder Code 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 Builder Code prompts you for them.

Connect the Contentful MCP server to Builder Code

Builder Code 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 Builder Code, 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.

Builder Code can now reach https://mcp.contentful.com/mcp on your behalf for any conversation in this workspace.

Choose a default project and dataset

Contentful organizes content into spaces and environments. Most teams want Builder Code 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." Builder Code passes that information through to subsequent MCP calls in that chat.

Disconnecting or re-authorizing

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 Builder Code workspace. Your Contentful data is untouched. Only Builder Code's access is revoked.

Disconnecting does not modify any code Builder Code has already written. If your app uses Contentful's standard SDK with an API key, that keeps working. The MCP connection is for Builder Code's own access during builds.

What Contentful MCP gives Builder Code

Once connected, Builder Code can call the Contentful MCP server's tools on its own when your prompt needs them. This provides several useful capabilities.

Capability	What Builder Code 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.

Builder Code 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, Builder Code calls the right MCP tools, generates the rendering code, and queries the SDK.

Common patterns

Several example of common prompts are included below.

Build a site against an existing Contentful space

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:

Builder Code calls list_content_types to confirm landingPage and caseStudy exist and learn their fields.
It pulls the first few entries with get_entries to 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 Builder Code 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, Builder Code makes a request for more information. Being specific saves tokens.

Bootstrap content modeling alongside the app

This type of prompt is best when you're starting from a blank Contentful space and want Builder Code 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_type to define Recipe with the fields you described.
A call to create_entry five 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 Builder Code at all.

Review the content types Builder Code proposes before letting it create them. A 10-second confirmation up front is cheaper than refactoring fields later.

Localized content

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."

Builder Code reads the locale configuration off your space and generates locale-aware fetches against Contentful's Delivery API.

Mix Contentful with other MCP integrations

Builder Code can use multiple MCP servers in one conversation. A typical pattern:

Contentful: used for marketing pages, blog, and product copy.
Stripe: used for pricing data and checkout.
Supabase or 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."

Best practices

Be explicit about space and environment when it matters. Builder Code uses your defaults from Manage, but on the first turn of a new conversation, it's worth instructing Builder Code to "use the master environment of the Marketing Space" to remove ambiguity.
Drafts vs. published. By default, Builder Code reads published entries using Contentful's CDA. If you're previewing unpublished work, tell Builder Code 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 Builder Code's access through OAuth. Runtime API keys for the generated app go into your project's environment variables. Builder Code tells you which ones to set.
Content types are case-sensitive. API IDs in Contentful are stable identifiers, for example.landingPage, not LandingPage or Landing Page. When in doubt, ask Builder Code 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 Builder Code 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), Builder Code's connection silently fails on the next call. Reconnect from Manage in Builder Code to fix it.
Multiple Contentful organizations. OAuth scopes Builder Code to the Contentful account you signed in with. If you have multiple organizations, sign in with the user who has access to the organization you need, or use Contentful's account switcher before clicking Connect.

Common fixes

"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.com during 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.

"Builder Code 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 Builder Code to "list content types in my default Contentful space". If it comes back empty, the issue is access, not the prompt.

"Builder Code writes to the wrong environment."

Builder Code 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—Builder Code can't undo a write after the fact.

"My editors don't get the new content types Builder Code 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 Builder Code) 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 Builder Code."

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.

What's next

Contentful's Model Context Protocol (MCP) server documentation for the full list of tools the MCP server exposes, including ones Builder Code reaches for on your behalf.
Builder Code integrations for the broader catalog of MCP servers Builder Code 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.

Was this article helpful?