Connect ButterCMS to Claude: Edit pages, posts, and data collections

If you are building an AI agent to manage your headless content infrastructure, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and ButterCMS's REST APIs. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses ChatGPT, check out our guide on connecting ButterCMS to ChatGPT or explore our broader architectural overview on connecting ButterCMS to AI Agents.

Giving a Large Language Model (LLM) read and write access to a headless CMS like ButterCMS is an engineering challenge. You have to handle API token lifecycles, map nested JSON schema definitions to MCP tool definitions, and deal with asynchronous write operations. Every time ButterCMS updates an endpoint or deprecates a content field, you have to update your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for ButterCMS, connect it natively to Claude Desktop, and execute complex content workflows using natural language.

The Engineering Reality of the ButterCMS API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against a headless CMS API is painful.

If you decide to build a custom MCP server for ButterCMS, you own the entire API lifecycle. Here are the specific challenges you will face:

Asynchronous Write Operations (202 Accepted) ButterCMS handles content creation and updates via its Write API asynchronously. When you create or update a page, a post, or a collection item, the API does not immediately return the updated object. Instead, it returns a 202 Accepted status with a processing status URL. If you expose this raw behavior to Claude, the LLM will often hallucinate that the data update failed because it did not receive a 200 OK with the final entity, or it will immediately try to fetch the content before the draft processing is complete. A managed integration layer helps contextualize this delay, allowing the AI agent to understand that the content is processing.

Polymorphic Page Retrieval ButterCMS separates "Page Types" (reusable templates) from "Single Pages" (one-off landing pages). Querying the API requires knowing this distinction. If you want to retrieve a specific page by its slug but you do not know its type, the ButterCMS API requires you to pass a wildcard * as the page_type parameter to look up a Single Page. Hardcoding this logic into a custom MCP server is tedious. Truto automatically injects this context into the tool descriptions, explicitly instructing the LLM on how to navigate the wildcard retrieval.

Transparent Rate Limiting and Backoff ButterCMS enforces rate limits on its endpoints to maintain performance. When an AI agent rapidly iterates through content collections or triggers mass updates, it will inevitably hit these limits. Truto does not attempt to absorb, retry, or throttle these requests - doing so often leads to silent timeouts in LLM runtimes. Instead, when ButterCMS returns a 429 Too Many Requests error, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized HTTP headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. Your AI agent (or Claude) is fully responsible for reading these headers and executing its own backoff strategy.

Instead of building this infrastructure from scratch, you can use Truto to auto-generate an MCP server that is already aware of these API nuances.

How to Generate a ButterCMS MCP Server with Truto

Truto dynamically generates MCP servers based on the ButterCMS API documentation and your connected account credentials. The resulting MCP URL contains a cryptographic token that securely maps to your specific ButterCMS environment.

You can generate this server via the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

If you want to quickly generate a server for Claude Desktop, use the dashboard:

1. Log into your Truto account and navigate to your Integrated Accounts.
2. Select your connected ButterCMS account.
3. Click on the MCP Servers tab.
4. Click Create MCP Server.
5. Configure your server (e.g., set a name like "ButterCMS Marketing", select allowed methods like read and write, and set an optional expiration date).
6. Click Save and copy the generated MCP server URL (it will look like https://api.truto.one/mcp/abc123def456...).

Method 2: Via the Truto API

For platform engineers building multi-tenant AI products, you can generate MCP servers programmatically for your users via the Truto REST API.

Make a POST request to /integrated-account/:id/mcp with your desired configuration:

curl -X POST https://api.truto.one/integrated-account/YOUR_ACCOUNT_ID/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ButterCMS Claude Server",
    "config": {
      "methods": ["read", "write"],
      "tags": ["content", "blog"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The API validates that the ButterCMS integration is active, generates a secure, hashed token in Cloudflare KV, and returns a ready-to-use URL:

{
  "id": "mcp-789",
  "name": "ButterCMS Claude Server",
  "config": { "methods": ["read", "write"] },
  "url": "https://api.truto.one/mcp/abc123def456"
}

Connecting the MCP Server to Claude

Once you have your Truto MCP URL, connecting it to Claude is a straightforward process. You do not need to install any local Node.js packages or Python servers - the URL is fully managed.

Method A: Via the Claude UI (Claude for Work / Custom Connectors)

If your organization uses Claude Enterprise or Team plans with Custom Connectors enabled:

1. Open Claude and navigate to Settings -> Integrations.
2. Click Add MCP Server or Add Custom Connector.
3. Paste the Truto MCP URL you generated.
4. Click Add.

Claude will immediately ping the endpoint, execute the initialize handshake, and populate its context window with the available ButterCMS tools.

Method B: Via Manual Config File (Claude Desktop)

If you are using the local Claude Desktop app for testing or personal use, you can configure the server via the claude_desktop_config.json file. Truto provides an official remote server bridge using the @modelcontextprotocol/server-sse package.

1. Open your configuration file:
   • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
2. Add the Truto server configuration:

{
  "mcpServers": {
    "buttercms-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/abc123def456"
      ]
    }
  }
}

Save the file and restart Claude Desktop. The app will spawn the SSE bridge and connect to your hosted Truto MCP server.

ButterCMS Hero Tools for Claude

Truto maps ButterCMS API endpoints into discrete, LLM-friendly tools. Below are the most critical tools for managing content via Claude.

1. list_all_butter_cms_pages_searches

This tool allows Claude to perform full-text searches across your ButterCMS pages. It returns matching pages sorted by relevancy. Note that only direct page content is searched - references are excluded from the initial search index but are appended to the response payload.

Contextual usage: Use this when Claude needs to audit existing content for a specific keyword or find a page before updating it.

"Claude, search our ButterCMS pages for any landing pages mentioning 'SOC 2 Compliance' and give me a summary of their current titles and slugs."

2. get_single_butter_cms_page_by_id

Retrieves a specific ButterCMS page by its type and slug. If you are retrieving a Single Page (a page not bound to a specific repeatable template), you must pass * as the page_type parameter to look up a Single Page.

Contextual usage: Use this to pull the exact schema and text of a page into context before drafting edits.

"Fetch the details for the ButterCMS page with the slug 'enterprise-pricing'. It is a Single Page, so use the wildcard page type."

3. update_a_butter_cms_page_by_id

Updates an existing ButterCMS page via the Write API using a partial PATCH request. Title and slug are immutable via this endpoint; you can only update the custom content fields. Processing is asynchronous.

Contextual usage: Use this to push copy changes directly to your staging or production environments.

"Update the 'enterprise-pricing' page in ButterCMS. Change the 'hero_subtitle' field to 'Secure infrastructure for global teams'."

4. list_all_butter_cms_contents

Retrieves items from a ButterCMS Collection. Collections are headless data tables commonly used for storing FAQs, authors, or global configuration data. The field structures vary based on your specific ButterCMS dashboard configuration.

Contextual usage: Use this to read structured data that feeds into your front-end components.

"List all items in the 'global_faqs' ButterCMS collection. Format the output as a clean list of questions and answers."

5. create_a_butter_cms_post

Creates a new ButterCMS blog post via the Write API. This tool supports author assignment, category tags, and SEO metadata. Posts are created as drafts by default. Scheduling is not supported on the initial create action.

Contextual usage: Use this to turn a drafted article in Claude directly into a CMS draft ready for human review.

"Create a new ButterCMS blog post titled 'Announcing our 2026 AI Features'. Use the content we just drafted for the body, and assign it to the 'Product Updates' category."

6. list_all_butter_cms_posts

Retrieves a paginated list of published ButterCMS blog posts, sorted by publication date (newest first). You can filter this list by author_slug, category_slug, or tag_slug.

Contextual usage: Use this to audit your blog history or check what content is currently live for a specific category.

"Pull the 10 most recent published posts from the ButterCMS blog under the 'Engineering' category and summarize their topics."

For the complete inventory of available tools, including detailed JSON schema representations of the request and response bodies, visit the ButterCMS integration page.

Workflows in Action

Connecting tools to Claude is only the first step. The real value of an MCP server is orchestrating multi-step API workflows through natural language.

Scenario 1: Auditing and Updating an SEO Landing Page

Marketing needs to update outdated product messaging across specific landing pages. Instead of logging into the CMS, finding the page, and copy-pasting text, you ask Claude to handle the update.

"Find our landing page about 'Automated Workflows'. Check the current SEO title, and then update the main body text to mention our new AI automation features."

Tool Execution Sequence:

1. list_all_butter_cms_pages_searches: Claude queries the API for "Automated Workflows" to locate the page slug (automated-workflows-2026) and verify the page type.
2. get_single_butter_cms_page_by_id: Claude retrieves the full page payload to inspect the current SEO metadata and exact field structure.
3. update_a_butter_cms_page_by_id: Claude pushes the revised body text to the specific content field using a partial PATCH request.

Result: Claude confirms the page was successfully updated and notes that because it is a Write API call, the change is currently processing asynchronously as a draft.

sequenceDiagram
  participant Claude as Claude Desktop
  participant Truto as Truto MCP Server
  participant Butter as ButterCMS API
  
  Claude->>Truto: Call list_all_butter_cms_pages_searches<br>{"query": "Automated Workflows"}
  Truto->>Butter: GET /v2/search/?query=...
  Butter-->>Truto: Return matched pages
  Truto-->>Claude: Page slug: automated-workflows-2026
  
  Claude->>Truto: Call get_single_butter_cms_page_by_id<br>{"id": "automated-workflows-2026", "page_type": "*"}
  Truto->>Butter: GET /v2/pages/*/automated-workflows-2026
  Butter-->>Truto: Full page schema
  Truto-->>Claude: Current SEO title & body
  
  Claude->>Truto: Call update_a_butter_cms_page_by_id<br>{"id": "automated-workflows-2026", "fields": {...}}
  Truto->>Butter: PATCH /v2/pages/*/automated-workflows-2026
  Butter-->>Truto: 202 Accepted (Processing)
  Truto-->>Claude: Update queued successfully

Scenario 2: Migrating a Local Document into a Blog Post

You have a local markdown file containing a technical tutorial. You want Claude to read the file, format it for the web, and publish it directly to your CMS.

"Read the local file 'tutorial.md'. Format the content into a ButterCMS blog post, generate a compelling SEO description, and create the post in ButterCMS as a draft under the 'Tutorials' category."

Tool Execution Sequence:

1. list_all_butter_cms_categories: Claude queries the available categories to ensure 'Tutorials' exists and retrieves its exact slug.
2. create_a_butter_cms_post: Claude executes the write operation, passing the formatted markdown as the post body, setting the SEO description, applying the category slug, and setting the status to draft.

Result: Claude reads the local system file, structures the data perfectly according to ButterCMS's required JSON schema, and confirms the new post is waiting in the CMS dashboard.

Security and Access Control

Exposing your production content management system to an LLM requires strict access control. Truto provides several mechanisms to lock down your MCP server and prevent destructive actions.

• Method Filtering: Using the config.methods array during server creation, you can strictly limit the MCP server to ["read"] operations. This ensures the LLM can search and pull content but cannot create, update, or delete pages, acting as a foolproof safety guardrail.
• Tag-Based Scoping: You can use config.tags to limit the server to specific resource domains. For example, applying ["blog"] ensures the LLM only has access to blog post endpoints and cannot touch critical landing pages or collections.
• API Token Authentication: For enterprise environments, you can enable config.require_api_token_auth. This forces the MCP client to pass a valid Truto API token in the Authorization header. Possession of the MCP URL alone is no longer sufficient to execute tools.
• Automatic Expiration: You can set an expires_at timestamp when creating the server. Once the time passes, Truto's durable objects automatically clean up the credentials in Cloudflare KV, making the URL invalid. This is ideal for granting contractors or temporary autonomous agents short-lived access to your CMS.

Connecting ButterCMS to Claude via a managed MCP server removes the friction of authenticating, mapping complex schemas, and handling asynchronous write logic. By leveraging Truto, your engineering team can stop maintaining integration code and start building autonomous content workflows.