Model Context Protocol (MCP) server

Table of contents

• Overview
• Remote vs local at a glance
• Choose your region (global vs. EU)
• Connect to Contentful MCP server
• Manage MCP client sessions
• Configure access per space and environment (Marketplace app)
  • Space/environment‑level configuration
  • How configuration works during connection
• Upload assets through the remote server
• Run a local MCP server
• Troubleshoot OAuth and connection issues
• Tools
• See also

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

Remote vs local at a glance

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.

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.

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

{
  "mcpServers": {
    "contentful": {
      "url": "https://mcp.contentful.com/mcp"
    }
  }
}

{
  "servers": {
    "contentful": {
      "type": "http",
      "url": "https://mcp.contentful.com/mcp"
    }
  }
}

claude mcp add --transport http contentful https://mcp.contentful.com/mcp

claude /mcp

{
  "mcpServers": {
    "contentful": {
      "serverUrl": "https://mcp.contentful.com/mcp"
    }
  }
}

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.

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, or it is installed through the tenant configuration UI the first time an admin connects (see How configuration works during connection).
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 exposed to 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.

How configuration works during connection

When a client first connects to https://mcp.contentful.com/mcp and completes OAuth:

1. You see a tenant configuration UI hosted by Contentful.

2. You select one or more space/environment pairs for the session (for example: space A / master, space B / staging).

3. For each selected environment:

• If the MCP app is already installed, its existing configuration determines available tools.
• If the MCP app is not installed and you have admin permissions, completing the configuration UI installs the app for you with the settings you choose.
• If you lack installation permissions, you’ll be prompted to ask an admin to install and configure the app.

4. These selections are stored in the MCP session, and every tool call is evaluated against:

• Your identity and your underlying Contentful permissions
• The current space/environment
• The MCP app configuration for that environment.

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:

{
  "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:

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:

{
  "spaceId": "<<YOUR_SPACE_ID>>",
  "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.

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

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.

{
  "mcpServers": {
    "contentful-local": {
      "command": "npx",
      "args": ["-y", "@contentful/mcp-server"],
      "env": {
        "CONTENTFUL_MANAGEMENT_ACCESS_TOKEN": "<<YOUR_CMA_PAT>>",
        "SPACE_ID": "<<YOUR_SPACE_ID>>",
        "ENVIRONMENT_ID": "master",
        "CONTENTFUL_HOST": "api.contentful.com"
      }
    }
  }
}

{
  "servers": {
    "contentful-local": {
      "command": "npx",
      "args": ["-y", "@contentful/mcp-server"],
      "env": {
        "CONTENTFUL_MANAGEMENT_ACCESS_TOKEN": "<<YOUR_CMA_PAT>>",
        "SPACE_ID": "<<YOUR_SPACE_ID>>",
        "ENVIRONMENT_ID": "master",
        "CONTENTFUL_HOST": "api.contentful.com"
      }
    }
  }
}

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.

• 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).

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

See also

• Contentful MCP server (open source) – GitHub repository and README with full tool list and examples.

• Model Context Protocol: The new AI connection standard – Blog post introducing MCP and how to use it with Contentful.