> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://contentful.com/developers/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/developers/docs/_mcp/server. # Model Context Protocol (MCP) server > Set up Model Context Protocol (MCP) server for AI agents to work with content across Contentful spaces and environments. ## Overview Let your AI agents interact with Contentful by using our MCP servers. The **Contentful Model Context Protocol (MCP) servers** provide tools that AI agents can use to read and write content, manage content models, work with assets, invoke AI Actions, and more, across your Contentful spaces and environments. Contentful offers: * A **remote, hosted MCP server** at `https://mcp.contentful.com/mcp`. * A **local, open‑source MCP server** you can run in your own environment. Both servers expose the same core toolset; they differ in how clients authenticate and how access is gated. If you're evaluating which to use, see [Remote vs local at a glance](#remote-vs-local-at-a-glance) below. ## Remote vs local at a glance | | **Remote MCP server** | **Local MCP server** | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Endpoint** | Hosted by Contentful at `https://mcp.contentful.com/mcp` | You run it yourself (Node.js / `npx @contentful/mcp-server`) | | **Authentication** | OAuth 2.1 — users sign in to Contentful through the client | Contentful Management API personal access token (PAT) supplied via environment variables | | **User identity** | Each user connects with their own Contentful identity | All tool calls run as the identity that owns the PAT | | **Permission gating** | Two layers: (1) the user's own Contentful permissions, and (2) a per‑space/per‑environment allow‑list managed by the Contentful MCP app (see [Configure access per space and environment](#configure-access-per-space-and-environment-marketplace-app)) | Single layer: whatever the supplied PAT can do. There is no per‑space, per‑environment, or per‑tool gating beyond the PAT itself | | **Space/environment scope** | Selected per session in the OAuth tenant configuration UI; can include multiple spaces/environments | Any space/environment the PAT can reach. `SPACE_ID` and `ENVIRONMENT_ID` environment variables are optional defaults the agent uses for context — every tool call still takes `spaceId` and `environmentId` arguments and can target a different space/env | | **Setup effort** | Zero infrastructure — just point a client at the URL | You provision a PAT and run the process locally (or in your own infra) | | **Best for** | Day‑to‑day use across teams; environments where central admins want to control which tools are exposed | Local development, scripting, CI, or environments where you can't use OAuth | > **Info** > > The remote MCP server depends on the **Contentful MCP app** being installed in each space/environment you want to use. The app handles per‑environment permission gating; on its own — without an MCP client connected to the remote server — it doesn't do anything. See [Configure access per space and environment](#configure-access-per-space-and-environment-marketplace-app) for how the app gets installed and configured. ## Choose your region (global vs. EU) Contentful runs the remote MCP server in two regions. Pick the endpoint that matches your organization's data residency requirements and use it everywhere you'd otherwise use the global URL. | Region | MCP endpoint | CMA routing | Sign-in | | ---------- | ----------------------------------- | ----------------------- | ---------------------- | | **Global** | `https://mcp.contentful.com/mcp` | `api.contentful.com` | `be.contentful.com` | | **EU** | `https://mcp.eu.contentful.com/mcp` | `api.eu.contentful.com` | `be.eu.contentful.com` | If your Contentful organization is provisioned in the EU region, use the EU endpoint so that authentication and all Content Management API calls stay within EU infrastructure. The region is fixed by the endpoint you connect to — there is no in-session switch. To move between regions, connect a client to the other endpoint. > **Info** > > All connection examples in this page use the global endpoint `https://mcp.contentful.com/mcp`. EU customers should substitute `https://mcp.eu.contentful.com/mcp` in every client configuration snippet below. ## Connect to Contentful MCP server Use the remote server if you want a zero‑infrastructure setup that works with popular MCP‑aware clients. All examples below use: ``` https://mcp.contentful.com/mcp ``` #### Cursor ```json { "mcpServers": { "contentful": { "url": "https://mcp.contentful.com/mcp" } } } ``` When Cursor first connects: 1. Cursor discovers that the server requires OAuth. 2. You're redirected to Contentful to sign in. 3. After signing in, you'll select which **spaces and environments** to connect (see "Configure access per space and environment" below). #### VS Code To use Contentful MCP from GitHub Copilot Chat with MCP support, add the following to your workspace's `.vscode/mcp.json`: ```json { "servers": { "contentful": { "type": "http", "url": "https://mcp.contentful.com/mcp" } } } ``` VS Code will: 1. Discover the MCP server at `https://mcp.contentful.com/mcp`. 2. Run the OAuth flow in your browser. 3. Use the resulting token to call Contentful tools from Copilot Chat in your chosen environments. #### Claude Code To use the remote MCP server from Claude Code: ```shell claude mcp add --transport http contentful https://mcp.contentful.com/mcp ``` Then start the MCP flow: ```shell claude /mcp ``` Claude opens a browser window for: 1. Signing in to Contentful. 2. Selecting the spaces and environments you want Claude to access. 3. Completing OAuth and returning to Claude with an MCP token scoped to those selections. #### ChatGPT You can enable MCP servers on ChatGPT (Pro, Plus, Business, Enterprise, or Education). Follow the OpenAI documentation for adding a custom MCP server and use: * **Server URL**: `https://mcp.contentful.com/mcp` * **Connection mechanism**: OAuth After you configure the server: 1. ChatGPT starts an OAuth flow in your browser. 2. You sign in to Contentful and choose which spaces/environments ChatGPT can work with. 3. The MCP session is then authorized only for those environments and tools you've enabled via the MCP marketplace app. #### Windsurf To use the remote MCP server from Windsurf, add the server to `~/.codeium/windsurf/mcp_config.json`: ```json { "mcpServers": { "contentful": { "serverUrl": "https://mcp.contentful.com/mcp" } } } ``` Then open Windsurf's MCP settings and refresh the server. Windsurf will: 1. Detect that the server requires OAuth. 2. Open your browser to sign in to Contentful. 3. Let you select which spaces and environments to connect before returning an MCP token scoped to those selections. #### Other MCP clients MCP is an open protocol supported by many clients. For any HTTP‑based MCP client: * **Server URL**: `https://mcp.contentful.com/mcp` * **Transport**: HTTP MCP base protocol * **Auth**: OAuth (recommended) ## Manage MCP client sessions The remote MCP server uses OAuth to connect clients to Contentful, following the MCP authorization spec for HTTP transports. When you add the Contentful MCP server to a client: 1. The client opens an OAuth consent flow in your browser. 2. You approve the client and select which **spaces/environments** are in scope for the session. 3. The MCP server exchanges the authorization code for an access token and issues an MCP‑specific token for subsequent tool calls. You can: * Re‑run the connection flow to update which environments are attached to a session. ## Configure access per space and environment (Marketplace app) The remote MCP server enforces a **per‑environment permission layer** through the **Contentful MCP app**. This lets admins decide exactly which tool categories are available in each environment, independent of the client being used. The app doesn't replace a user's underlying Contentful permissions — it sits on top of them as an additional allow‑list. > **Info** > > **How the app relates to the remote server**: The MCP app is a permission‑gating mechanism, not a server. Installing the app on its own gives you nothing usable — you also need an MCP client pointed at `https://mcp.contentful.com/mcp`. Conversely, the remote server cannot be used in a space/environment until the MCP app is installed and configured there. The app is available directly in the Marketplace, and it is also installed automatically when an admin completes the tenant configuration UI for a space/environment (see below). ### Space/environment‑level configuration For each environment where you want to use the remote MCP server: 1. The **Contentful MCP app** must be installed into the space and environment. You can install it directly from the Marketplace. 2. Open the app's **configuration screen**. 3. Select the tool categories that you would like to be allowed for that environment (for example: entries, assets, content types, environments, AI Actions). 4. For the selected tool categories, select either **read‑only** or **read/write**. At runtime: * The remote MCP server looks up the MCP app configuration for the space + environment currently in use. * Only tools enabled in that config are callable by MCP clients; disabled tools are rejected even if a client tries to call them directly. * All users connecting to that environment via the remote MCP server share the same allow‑list, but are still subject to their own underlying Contentful permissions. ## Upload assets through the remote server MCP tool calls are JSON over HTTP, so binary files (images, PDFs, and other media) can't be sent through a normal tool call. The remote server uses a two-phase upload: 1. Stage the raw bytes. 2. Bind them to a Contentful asset. To upload assets through the remote server: 1. **Create an upload session.** Call the `create_upload_session` tool (no arguments). It returns a short-lived session: ```json { "uploadHandle": "9f2c…", "uploadUrl": "https://mcp.contentful.com/uploads/9f2c…", "expiresAt": "2026-06-08T13:00:00.000Z" } ``` 2. **Upload the bytes.** `PUT` the raw file bytes to the returned `uploadUrl` with a `Content-Length` header. This endpoint is intentionally unauthenticated — the `uploadHandle` itself is the capability token, so treat it like a secret: ```shell curl -X PUT "https://mcp.contentful.com/uploads/9f2c…" \ --data-binary @image.png \ -H "Content-Length: $(wc -c < image.png)" ``` 3. **Create the asset.** Call the `upload_asset` tool with the handle so the server retrieves the staged bytes and creates the Contentful asset: ```json { "spaceId": "<>", "environmentId": "master", "file": { "uploadHandle": "9f2c…", "fileName": "image.png", "contentType": "image/png" } } ``` Upload sessions expire **one hour** after creation and are **single-use** — once an asset is created from a handle (or the handle expires), the handle can't be reused. Create a fresh session for each upload. > **Info** > > **ChatGPT**: When connected through ChatGPT, skip `create_upload_session` entirely. Attach the file to the conversation and call `upload_asset` directly — ChatGPT passes the file to the server for you. > **Info** > > **EU region**: Asset upload is supported on the EU endpoint as well. The `uploadUrl` returned by `create_upload_session` is absolute and already points at the correct host (for example `https://mcp.eu.contentful.com/uploads/`), so always PUT to the URL the tool returns rather than constructing it yourself. ## Run a local MCP server If you prefer or require a local setup, use the **local Contentful MCP server** from our open‑source repository: * GitHub: [`https://github.com/contentful/contentful-mcp-server`](https://github.com/contentful/contentful-mcp-server) The local server: * Runs as a Node.js application on your own machine or infrastructure. * Authenticates with a **Contentful Management API personal access token (PAT)** that you supply via environment variables — there is no OAuth flow. * Can address any space and environment the PAT has access to. `SPACE_ID` and `ENVIRONMENT_ID` are optional environment variables that act as default context for the agent (surfaced via `get_initial_context`); every tool call still accepts `spaceId` and `environmentId` arguments and can target a different space or environment within the same process. * Exposes the same core toolset as the remote server, but **doesn't use the Contentful MCP app** for permission gating. Every tool call runs as the PAT's owner, with whatever permissions that PAT has — there is no per‑environment or per‑tool allow‑list. Treat the PAT itself as the security boundary, and prefer a token scoped to the minimum permissions you need. #### Cursor Add this to your `~/.cursor/mcp.json`: ```json { "mcpServers": { "contentful-local": { "command": "npx", "args": ["-y", "@contentful/mcp-server"], "env": { "CONTENTFUL_MANAGEMENT_ACCESS_TOKEN": "<>", "SPACE_ID": "<>", "ENVIRONMENT_ID": "master", "CONTENTFUL_HOST": "api.contentful.com" } } } } ``` #### VS Code For GitHub Copilot Chat with MCP support, add to `.vscode/mcp.json`: ```json { "servers": { "contentful-local": { "command": "npx", "args": ["-y", "@contentful/mcp-server"], "env": { "CONTENTFUL_MANAGEMENT_ACCESS_TOKEN": "<>", "SPACE_ID": "<>", "ENVIRONMENT_ID": "master", "CONTENTFUL_HOST": "api.contentful.com" } } } } ``` #### Other local MCP clients For other local‑execution MCP clients (Windsurf, Claude Desktop, etc.), configure a server entry that: * Runs `npx -y @contentful/mcp-server` (or your built binary). * Supplies the same environment variables (`CONTENTFUL_MANAGEMENT_ACCESS_TOKEN`, `SPACE_ID`, `ENVIRONMENT_ID`, `CONTENTFUL_HOST`). ## Troubleshoot OAuth and connection issues Most remote-server problems come down to authentication or per-environment configuration. Work through these common pitfalls first if you are having trouble connecting: * **A tool you expect returns a "not allowed" error**: Tool availability is gated per environment by the Contentful MCP app, on top of your own Contentful permissions. If a tool is being blocked because of your permissions configuration, that tool category has likely not been authorized for that space/environment. Try updating the app's configuration, then re-run the connection flow. See [Configure access per space and environment](#configure-access-per-space-and-environment-marketplace-app). * **The browser never opens, or sign-in fails**: Your client may have cached a stale or revoked token. Remove and re-add the Contentful MCP server in your client so it re-runs the OAuth flow from scratch. * **You're an EU customer and calls fail or route to the wrong region**: Make sure every client snippet points at `https://mcp.eu.contentful.com/mcp`, not the global endpoint. Region is determined by the endpoint you connect to — see [Choose your region (global vs. EU)](#choose-your-region-global-vs-eu). * **You get a `Failed to fetch app installation: Forbidden` error when running tools**: The most common cause is using an **environment alias**. Environment aliases are not currently supported. Connect to and reference the **underlying environment ID directly** instead of the alias. * **Make sure to select a space and environment every time you connect**: Even when the MCP app is already installed in an environment, each new connection's configuration screen requires you to select the space/environment pair(s) for that session. Selecting them again does not reinstall or reconfigure the app — it scopes the current session. If you skip this, the session has nothing to operate on. ## Tools The Contentful MCP servers expose the following tool categories. The remote server filters these per environment based on MCP app configuration; the local server exposes all tools allowed by your token. | Resource / Domain | Tools | Description | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Context & Setup** | `get_initial_context` | Initialize connection and return usage instructions. | | **Entries** | `search_entries`, `semantic_search`, `get_entry`, `create_entry`, `update_entry`, `publish_entry`, `unpublish_entry`, `archive_entry`, `unarchive_entry`, `delete_entry`, `get_entry_snapshot`, `resolve_entry_references` | Manage content entries end‑to‑end, including semantic search, archiving, version snapshots, and reference resolution. | | **Content Types** | `list_content_types`, `get_content_type`, `create_content_type`, `update_content_type`, `publish_content_type`, `unpublish_content_type`, `delete_content_type`, `delete_content_type_field`, `disable_content_type_field`, `omit_content_type_field` | Inspect and evolve your content model, including field‑level changes. | | **Assets** | `upload_asset`, `create_upload_session`, `list_assets`, `get_asset`, `update_asset`, `publish_asset`, `unpublish_asset`, `archive_asset`, `unarchive_asset`, `delete_asset` | Upload, organize, archive, and publish media assets. | | **Releases** | `list_releases`, `get_release`, `create_release`, `update_release`, `publish_release`, `unpublish_release`, `validate_release`, `get_release_action`, `list_release_actions`, `schedule_publish_release`, `schedule_unpublish_release`, `cancel_scheduled_release`, `list_scheduled_actions` | Group entries and assets into a release, then validate, publish, or unpublish them together (immediately or on a future schedule) and check the status of those queued actions. | | **Spaces & Environments** | `list_spaces`, `get_space`, `list_environments`, `create_environment`, `delete_environment` | Discover and manage spaces and environments. | | **Organizations** | `list_orgs`, `get_org` | Discover the organizations your identity can access. | | **Locales** | `list_locales`, `get_locale`, `create_locale`, `update_locale`, `delete_locale` | Configure and manage locales for multi‑language content. | | **Tags** | `list_tags`, `create_tag` | Work with tags for organizing content. | | **AI Actions** | `create_ai_action`, `invoke_ai_action`, `get_ai_action`, `get_ai_action_invocation`, `list_ai_actions`, `update_ai_action`, `publish_ai_action`, `unpublish_ai_action`, `delete_ai_action` | Create and invoke AI‑powered workflows with Contentful AI Actions. | | **Taxonomy** | `list_concepts`, `get_concept`, `create_concept`, `update_concept`, `delete_concept`, `list_concept_schemes`, `get_concept_scheme`, `create_concept_scheme`, `update_concept_scheme`, `delete_concept_scheme` | Manage concepts and concept schemes in the taxonomy system. | | **Editor Interfaces** | `get_editor_interface`, `list_editor_interfaces`, `update_editor_interface` | Inspect and configure how fields appear in the entry editor. | > **Info** > > **Security note**: When using the remote MCP server, we recommend enabling human confirmation of tool calls in your client wherever possible, and starting with read‑only enablements in the MCP app before turning on write capabilities. ## See also * [Contentful MCP server](https://github.com/contentful/contentful-mcp-server) (open source) – GitHub repository and README with full tool list and examples. * [Model Context Protocol: The new AI connection standard](https://www.contentful.com/blog/model-context-protocol-introduction/) – Blog post introducing MCP and how to use it with Contentful.