How to Use the ButterCMS MCP in OpenAI Agents SDK

Q: How do I initialize the ButterCMS MCP Server in my OpenAI Agents SDK project?

Install openai-agents first. Then, spin up the server using the MCPServerStreamableHttp class with your Vinkius endpoint. Pass that instance into the mcpservers list when you instantiate your Agent.

Q: Can my OpenAI Agents SDK handle complex layouts from ButterCMS?

Yes, it can. The agent uses the getpagelayout tool to inspect the active UI routing. It reads the raw JSON structure of your custom pages so it can make decisions based on your real design layouts.

Q: Does the OpenAI Agents SDK support caching for ButterCMS tool definitions?

It does. Set cacheToolsList=True inside your agent configuration to avoid fetching the tool schemas on every single run. This speeds up response times when your agent calls listbutterauthors or listbuttercategories.

Q: How does the agent search through blog posts inside ButterCMS?

The agent invokes searchblogposts with your target keyword. It returns matching posts, which the agent can then drill into using getpostdetails to extract the full body text or meta description.

Connect your OpenAI Agents SDK to ButterCMS. Let your agents fetch layouts, pull blog posts, and manage content on autopilot.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect ButterCMS MCP to OpenAI Agents SDK

Create your Vinkius account to connect ButterCMS to OpenAI Agents SDK and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup ButterCMS with OpenAI Agents SDK

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Run Safe ButterCMS Queries with OpenAI Agents SDK

Stop letting raw LLMs guess your CMS structure. This MCP Server lets your OpenAI agents pull actual structured data directly from your ButterCMS account. By calling `get_page_layout` and `list_custom_pages`, your agents inspect live schemas and route UI elements without breaking your front-end production code. The OpenAI Agents SDK runs these tools with built-in guardrails that you define. If an agent tries to fetch a layout that does not exist, the SDK catches the error before it hits your production environment. You get clean execution logs on your OpenAI dashboard for every single CMS call.

Search and Route Blog Content Dynamically

Finding specific content in a massive headless CMS is usually a headache. With `search_blog_posts` and `list_blog_posts`, your agent scans your entire ButterCMS library in seconds. It matches exact keywords and locates specific post slugs without making you write custom API queries. We use the SDK's multi-agent handoff features to run this smoothly. One specialized writer agent can draft a newsletter, while a search agent calls `get_post_details` to verify old blog links. It keeps your content pipeline moving without manual copy-pasting.

Pull Structured Collections and Tags

Managing taxonomy should not require manual database lookups. The `list_butter_tags` and `list_global_collections` tools expose your global structures directly to the agent. It reads your exact categories, tags, and custom collections so it knows exactly how your content is organized. Once the agent gets this structural data, it maps taxonomy hits to your active web CRM boundaries. You do not have to worry about the agent hallucinating tag names. It only uses what actually exists inside your ButterCMS dashboard.

Setup guide

Set up ButterCMS MCP in OpenAI Agents SDK

Prerequisites

Python 3.10+ installed
openai-agents package (pip install openai-agents)
Active Vinkius subscription with a valid endpoint token

1

Install the SDK

Run pip install openai-agents to install the OpenAI Agents SDK. The MCP integration is built-in — no extra dependencies needed.
2

Connect via SSE transport

Use MCPServerSse with your Vinkius endpoint URL. Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com. The SDK auto-discovers all ButterCMS tools at runtime.
3

Create your Agent

Pass the MCP to Agent(mcp_servers=[server]). The agent receives ButterCMS tools as native definitions — JSON schemas resolve automatically.
4

Run the agent

Call Runner.run(agent, prompt) to execute. The agent invokes the appropriate ButterCMS tools and returns structured results. Copy the full example on the right to get started.

agent.py

import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerSse

async def main():
    async with MCPServerSse(
        url="https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
    ) as server:
        agent = Agent(
            name="ButterCMS Agent",
            instructions="You have access to ButterCMS tools.",
            mcp_servers=[server],
        )
        result = await Runner.run(agent, "List recent transactions")
        print(result.final_output)

asyncio.run(main())

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by ButterCMS. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect ButterCMS now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about ButterCMS MCP in OpenAI Agents SDK

Install `openai-agents` first. Then, spin up the server using the `MCPServerStreamableHttp` class with your Vinkius endpoint. Pass that instance into the `mcp_servers` list when you instantiate your Agent.

Yes, it can. The agent uses the `get_page_layout` tool to inspect the active UI routing. It reads the raw JSON structure of your custom pages so it can make decisions based on your real design layouts.

It does. Set `cacheToolsList=True` inside your agent configuration to avoid fetching the tool schemas on every single run. This speeds up response times when your agent calls `list_butter_authors` or `list_butter_categories`.

The agent invokes `search_blog_posts` with your target keyword. It returns matching posts, which the agent can then drill into using `get_post_details` to extract the full body text or meta description.

Your API tokens are locked inside Vinkius's zero-trust V8 sandbox and never exposed to the LLM. The OpenAI Agents SDK only sees the tool schemas and the raw blog content returned by the API. No draft posts or layout configurations are stored on our servers.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript