DEV Community: Tony Spiro

MCP vs Agent Skills: What's the Difference and Which Do You Need?

Tony Spiro — Tue, 12 May 2026 22:12:48 +0000

Originally published at cosmicjs.com

Two terms keep coming up in every AI developer conversation right now: MCP (Model Context Protocol) and Agent Skills. They sound similar. They're not the same thing. Here's a clear breakdown of what each is, when to use which, and how Cosmic implements both.

What Is MCP?

MCP (Model Context Protocol) is an open protocol developed by Anthropic that lets AI models connect to external tools and data sources in a standardized way. Think of it as a universal adapter that allows an AI assistant like Claude to read files, query databases, call APIs, and interact with services, all through a consistent interface.

MCP runs as a server that your AI client connects to. Once connected, the AI can discover and use whatever tools the MCP server exposes.

Cosmic MCP Server: Cosmic ships a native MCP server that gives AI assistants direct access to your content. Claude, Cursor, and other MCP-compatible clients can read objects, query content types, fetch media, and understand your content model, all without you writing any integration code.

What Are Agent Skills?

Agent Skills are pre-built, reusable capabilities you can attach to AI coding assistants like Cursor, Claude Code, and GitHub Copilot. Where MCP gives an AI access to data, Agent Skills give an AI knowledge of how to do specific tasks in a specific codebase or platform.

CosmicAgent Skills teach your coding assistant how to work with Cosmic specifically: how to structure queries, how to use the TypeScript SDK, how to model content, and how to build features against the Cosmic REST API.

The Key Difference

MCP = data access. The AI can read and write to your Cosmic bucket in real time.
Agent Skills = task knowledge. The AI knows how to build with Cosmic correctly.

They are complementary, not competing.

When to Use MCP

Use the Cosmic MCP Server when:

You want Claude or another AI assistant to query your live content
You're using an AI chat interface and want it to have context about your bucket
You want AI to help you manage, audit, or restructure your content

# Add Cosmic MCP to your Claude config
npx @cosmicjs/mcp

When to Use Agent Skills

Use Cosmic Agent Skills when:

You're building features in Cursor, Claude Code, or Copilot
You want your coding assistant to generate correct Cosmic SDK code automatically
You want to avoid copy-pasting docs into every prompt

Using Both Together

The most powerful setup uses both. Your coding assistant has Agent Skills so it generates correct Cosmic code, and it has MCP access so it can query your actual live bucket while building. It can look up your real content types, check what fields exist, and generate code that matches your exact schema.

// Agent Skills ensure your assistant generates correct SDK usage
import { createBucketClient } from '@cosmicjs/sdk'

const cosmic = createBucketClient({
  bucketSlug: process.env.COSMIC_BUCKET_SLUG,
  readKey: process.env.COSMIC_READ_KEY
})

// MCP gives the assistant live access to your actual content types
const { objects } = await cosmic.objects
  .find({ type: 'your-actual-type-slug' }) // AI knows this from MCP
  .props('title,slug,metadata')
  .limit(10)

The Bottom Line

If you're building with AI assistants, you want both. MCP for live data access. Agent Skills for correct code generation. Cosmic ships both natively.

Start free with Cosmic and set up both in under 10 minutes.

Astro vs Next.js: Which Framework Should You Use in 2026?

Tony Spiro — Tue, 12 May 2026 22:12:26 +0000

Originally published at cosmicjs.com

Choosing between Astro and Next.js in 2026? Both are excellent frameworks, but they solve different problems. This guide breaks down the real tradeoffs so you can make the right call for your project.

The Short Answer

Use Astro when your site is content-heavy and you want maximum performance with minimal JavaScript. Use Next.js when you need a full-stack React application with dynamic data, auth, and API routes.

Both work seamlessly with Cosmic as your headless CMS.

What Astro Does Well

Zero JS by default, ships only what you need
Island architecture for selective hydration
Supports React, Vue, Svelte, and more in the same project
Best-in-class for static content sites, blogs, and marketing pages
Built-in content collections

What Next.js Does Well

Full-stack React with App Router and Server Components
API routes and server actions built in
ISR and on-demand revalidation
Largest ecosystem and community
Best for dynamic applications, dashboards, and e-commerce

Performance Comparison

Astro wins on raw page weight for content sites. No framework JavaScript ships by default. Next.js with proper server components is competitive, but requires more discipline to keep bundles lean.

When to Use Astro

Marketing sites and landing pages
Blogs and documentation
Content-heavy sites where SEO is the primary goal
Teams that want to mix component frameworks

When to Use Next.js

SaaS applications
E-commerce with dynamic inventory
Apps with complex auth flows
Teams already invested in the React ecosystem

Using Both with Cosmic

Cosmic's REST API and TypeScript SDK work identically in both frameworks. Here's how to fetch content in each:

Astro

import { createBucketClient } from '@cosmicjs/sdk'

const cosmic = createBucketClient({
  bucketSlug: process.env.COSMIC_BUCKET_SLUG,
  readKey: process.env.COSMIC_READ_KEY
})

const { objects } = await cosmic.objects
  .find({ type: 'blog-posts' })
  .props('title,slug,metadata')
  .limit(10)

Next.js App Router

import { createBucketClient } from '@cosmicjs/sdk'

const cosmic = createBucketClient({
  bucketSlug: process.env.COSMIC_BUCKET_SLUG,
  readKey: process.env.COSMIC_READ_KEY
})

export default async function BlogPage() {
  const { objects } = await cosmic.objects
    .find({ type: 'blog-posts' })
    .props('title,slug,metadata')
    .limit(10)

  return <div>{objects.map(post => <div key={post.slug}>{post.title}</div>)}</div>
}

Same SDK, same API, same content model. Switch frameworks without touching your content.

The Verdict

Astro and Next.js are not competitors in the traditional sense. They serve different primary use cases. The better question is: what are you building?

Content site with SEO focus? Astro. Full-stack application? Next.js. Both? Cosmic works with either.

Start free with Cosmic and build with whichever framework fits your project.

AI as Coordinator: Why SaaS Must Bundle or Die

Tony Spiro — Tue, 12 May 2026 16:03:23 +0000

For most of the last decade, the conventional wisdom in software was simple: use the best tool for every job. The CRM that wins on contact management. The CMS that wins on editor experience. The analytics platform that wins on dashboards. The best-of-breed stack, stitched together by integrations and held together by the humans navigating between them.

That era is over. I don't think this is coming. I think it has already happened. And I don't think most SaaS companies understand the implications yet.

The Unbundling Era Made Sense When Humans Were the Coordinators

The logic behind best-of-breed stacks was always human logic. A skilled operator could hold context across a dozen tools. A marketing manager could pull data from one platform, paste it into another, run a report from a third, and synthesize the whole picture in her head. The friction of context-switching was manageable because humans are actually pretty good at it. We pattern-match across interfaces. We tolerate inconsistency. We remember which export format a specific tool uses.

The integration layer was built for us. Zapier, Make, and dozens of custom webhooks exist because humans needed to connect tools they were already using. The business value was locked inside each individual product. The human was the orchestration layer.

So the market optimized for exactly that model. Single-purpose tools got sharper, deeper, and more opinionated. The pitch was always the same: we do one thing and we do it better than anyone. If you want the best email tool, use us. If you want the best CMS, use us. Mix and match as needed.

It was a good model. For a while.

Agents Don't Care About Dashboard Design

Here's what changes when AI agents become the coordinators of business operations: agents don't navigate between tools the way humans do. They don't have the cognitive flexibility to tolerate seams. They operate through APIs, CLIs, and MCPs, and every API boundary is a potential failure point: an authentication handoff that breaks, a data schema that doesn't translate cleanly, a rate limit that introduces latency, an error state that the agent doesn't know how to recover from.

Agents don't care about dashboard design. They don't appreciate a beautiful UI. The entire value proposition of the best-of-breed stack collapses when the end user is not a human.

An agent operating across 12 separate SaaS tools is not more capable than an agent operating in one unified system. It's more fragile. More likely to fail at a handoff. More likely to produce inconsistent output. More expensive to maintain. More difficult to debug.

The seams that humans could paper over with judgment and context-switching become hard failures when an agent hits them.

The New Moat Isn't UI. It's Vertical Integration.

This is where I think much of the software industry is getting it wrong. A lot of SaaS companies are responding to the AI moment by adding AI features. A copilot here. An AI-assisted editor there. An auto-summarize button on the dashboard. These features are fine, but they don't change the fundamental problem.

The companies that will win the next decade are not the ones that added AI on top of their existing product. They're the ones that rethought the product architecture entirely, with agents as the primary user.

The new moat is vertical integration. It's owning the full stack that an agent needs to do a job, in a single system, with a single data model, through a single API.

The single-product SaaS company with a great UI is not just at a disadvantage. It is structurally exposed.

From User Experience to Agent Experience

For the last decade, premium software competed on UX. Smoother onboarding. Cleaner dashboards. More intuitive editors. The best product was the one your team actually wanted to open in the morning.

That era produced real value. But it also produced an entire generation of software optimized for the wrong user.

The new benchmark is Agent Experience. AX. How well does your platform perform when the user is an AI agent making thousands of API calls, not a human clicking through a dashboard?

AX is not about aesthetics. It is about architecture. A high-AX platform has a unified data model, a clean and comprehensive API, minimal failure surfaces at integration boundaries, and built-in orchestration so agents don't need to reach outside the system to complete a workflow.

A vertically integrated platform is not just more convenient for agents. It is architecturally superior for them. Every seam an agent doesn't have to cross is a failure point eliminated, a latency reduced, a context preserved.

The logical endpoint of this architecture is a platform where agents don't just create content, they also measure its performance and act on what they learn. When the same system owns the content object and the pageview that came from it, the loop closes. Write, ship, measure, learn, all inside one platform, all accessible to your agents without a single third-party integration. That is what vertically integrated AX looks like in practice. We are building toward it.

UX won the last decade. AX wins the next one.

Who Loses

The companies most at risk are the ones whose entire value proposition was "we do one thing better than anyone."

Point solutions that relied on being the best-in-class editor, the best-in-class analytics view, or the best-in-class content modeling interface are going to find that the interface advantage no longer matters when agents are the users. An agent doesn't prefer your drag-and-drop UI. It calls your API.

The companies that built moats through beautiful interfaces are going to find that those moats are much shallower than they thought.

Who Wins

The companies that win will have a few characteristics in common.

First, they'll have a unified data model. Second, they'll expose a clean, comprehensive API as the primary interface. Third, they'll own the vertical. Fourth, they'll have built-in orchestration.

The Headless CMS Example

The headless CMS space is a useful lens here, because it's a sector that went through aggressive unbundling in the last five years and is now running directly into this problem.

The headless CMS companies that survive this shift will be the ones that extended beyond pure content APIs before the window closed.

Cosmic as the Model

I'm not writing this as an abstract observation. This is the exact bet we made at Cosmic.

Today, Cosmic is a single system that covers content management, media processing and delivery, AI agent infrastructure, workflow automation, and deployment. Our customers' agents can write a content draft, pull from the media library, run it through a publishing workflow, and deploy it, all through one API, in one system, with one data model.

When FINN, one of our customers, describes the value, Co-Founder Maximilian Wuhr puts it simply: "Cosmic is: us never having to ask a developer to change anything on the backend of our website."

The Window Is Shorter Than You Think

The companies that figure this out in the next 18 months will build the infrastructure their AI-native customers depend on. The companies that wait are betting that their existing moats hold longer than the market is moving.

Bundling isn't a retreat from the sophistication of the unbundled era. It's the appropriate response to the fact that the coordinator changed.

Bundle or die isn't hyperbole. It's the engineering reality of building for agents.

UX won the last decade. AX wins the next one.

If you're building for the agentic era and want to see what integrated depth actually looks like in production, start free at cosmicjs.com or book a 30-minute intro with Tony.

Tony Spiro is the CEO of Cosmic. He writes about building AI-native teams, headless CMS architecture, and the future of content infrastructure.

What Agent-Native Means for Your Content Infrastructure

Tony Spiro — Mon, 11 May 2026 21:41:02 +0000

"Agent-native" is being claimed by a lot of companies right now. Here's what it actually means at the content infrastructure layer — where agents read, write, and publish the content that everything else depends on.

Every Layer Is Being Redesigned

Every layer of the software stack is being redesigned for AI agents. The frontend layer, the code layer, the deployment layer. But there's one layer getting less attention — and it's the one agents depend on most: the content infrastructure layer. That's the CMS.

Here's what I think "agent-native" actually means at that layer, and why it matters.

Agents Need to Read, Write, and Publish Content

Let's start with the obvious: AI agents work with content. They generate it, organize it, update it, and publish it. The CMS is where that content lives. So if your CMS wasn't built for agents to interact with directly, your entire AI workflow has a bottleneck at the most important layer.

A traditional CMS was designed for a human editor sitting at a dashboard. An agent-native CMS is designed for agents — and humans — to operate it equally well.

For Cosmic, this meant four concrete things:

First: The API had to be simple enough for any AI agent to consume without special training. REST over HTTP, predictable URL patterns, JSON responses. Not a custom query language. Not a schema you need to introspect before you can use it.

Second: Agents needed to be first-class objects in the product. Not bolt-on integrations. Not webhooks you configure manually. Native AI agents — Team, Content, Code, Computer Use — that live in your workspace and operate on your content autonomously.

Third: The CMS had to connect to where developers already work. That's your IDE. So we built an MCP Server and Agent Skills for Cursor, Claude Code, and GitHub Copilot. Your AI coding tool can now read and write CMS content without leaving your editor.

Fourth: Agents needed to chain together. A Content Agent drafts an article. A Code Agent updates the front-end component. A Computer Use Agent cross-posts to social. A Team Agent notifies the editor in Slack. This is a workflow — and it needs to run on a schedule or a webhook trigger, without a human in the loop.

What This Unlocks for Teams in 2026

When your content infrastructure is genuinely agent-native, a few things become possible that weren't before.

Content velocity stops being a headcount problem. A single editor working with a team of content agents can produce, manage, and publish at a scale that previously required a full content department.

Developers get their time back. When agents handle the routine CMS work — bulk updates, content audits, migration tasks — developers can focus on the work that actually requires human judgment.

The feedback loop between content and code collapses. When your Content Agent and your Code Agent are in the same workflow, a content change can trigger a code update, a preview deployment, and a Slack notification in a single automated run.

This is not a future state. These are things teams are doing with Cosmic today.

The CMS Is the Critical Layer

Every AI agent that touches your product — regardless of what framework it's built in or which LLM it runs on — eventually needs to read or write content. That makes the CMS the most critical layer in an agent-native stack.

And it's the layer that will determine whether your agent workflows are fast, reliable, and actually useful, or slow, fragile, and constantly requiring human intervention.

Agent-native content infrastructure is not about adding an AI button to a dashboard. It's about rebuilding the CMS from the ground up for a world where agents and humans work on the same content, in the same system, at the same time.

That's what we're building at Cosmic.

I'm the CEO of Cosmic, an AI-powered headless CMS. I write about building AI-native teams and the future of content infrastructure.

Originally published on the Cosmic blog: https://www.cosmicjs.com/blog/agent-native-content-infrastructure

Why Cosmic Uses REST (and Why That's the Right Call in 2026)

Tony Spiro — Mon, 11 May 2026 21:37:22 +0000

Why Cosmic Uses REST (and Why That's the Right Call in 2026)

Every few years, a new API paradigm gets declared the future. GraphQL had its moment. And it's genuinely good — for certain use cases. But "good for certain use cases" and "better default for most teams" are different claims. REST is still the right default, and in 2026 there's a new reason it matters: AI agents.

Here's an honest breakdown of the tradeoffs, and why Cosmic is REST-first by design.

The Honest GraphQL vs REST Comparison

Let's be direct about where each one wins.

Where GraphQL excels

Precisely shaped responses. GraphQL lets clients request exactly the fields they need. On mobile or low-bandwidth environments, this can meaningfully reduce payload size.
Single endpoint for complex graphs. When your data has deeply nested relationships and you need to traverse them in a single request, GraphQL's query model can simplify client code.
Rapid iteration on the client side. Frontend teams can adjust what data they fetch without waiting for a backend API change.
Type-safe schema introspection. Tooling like Apollo DevTools and GraphQL Codegen is genuinely excellent for teams that invest in the ecosystem.

Where REST wins

Simplicity. A REST endpoint is a URL. Any HTTP client — curl, fetch, Postman, a Python script, an AI agent — can consume it without understanding a schema or learning a query language.
Cacheability. HTTP caching is built for REST. GET requests to a stable URL can be cached at the CDN layer with no additional tooling. GraphQL's POST-by-default convention makes this harder.
Debuggability. When something breaks, a REST API gives you a URL you can open in a browser, paste into Postman, or log directly. GraphQL errors can be harder to trace without dedicated tooling.
Ecosystem breadth. REST is universal. Every language, every framework, every tool speaks REST.
Operational simplicity. No query parser, no resolver overhead, no N+1 query problems to solve. For most content APIs, the queries are simple enough that REST's structure is a feature, not a limitation.

The honest verdict on GraphQL

GraphQL makes sense for complex, client-driven data fetching scenarios — large product catalogs with dozens of relationship types, mobile apps with strict bandwidth constraints, teams with mature frontend infrastructure. It's a real tool for real problems.

But most content APIs are not that complex. A blog post has a title, a body, some metadata, and maybe a category. A landing page has sections and a hero image. REST handles these cases cleanly, with less overhead and more cacheability.

Why 2026 Changes the Calculation: AI Agents

Here's the new variable: AI agents are now part of most content workflows. And REST is dramatically better suited for agent consumption than GraphQL.

REST endpoints are trivially parseable by LLMs

A REST endpoint is a URL with predictable structure: GET /objects?type=blog-posts&limit=10. An AI agent can construct this URL from a natural language instruction without understanding a schema. The response is JSON — structured, flat, predictable.

GraphQL requires the agent to understand the schema, construct a valid query document, and handle the query syntax correctly. That's more tokens, more failure modes, and more prompting complexity.

Caching matters for agent workflows

AI agents often make repeated, similar requests — checking content status, fetching object counts, reading metadata. CDN-cached REST responses make this cheap and fast. GraphQL's POST-by-default pattern bypasses CDN caching entirely, meaning every agent request hits your origin.

Direct URL-based queries are auditable

When an AI agent fetches content via a REST endpoint, the request is a plain URL you can log, inspect, and replay. This matters for debugging agent workflows and for understanding what your agents are actually doing.

The emerging standard: REST + structured JSON

Tools like Model Context Protocol (MCP) and the major LLM provider SDKs are all built around REST + JSON. The ecosystem is converging on REST as the lingua franca for agent-to-service communication — because it's the most universally parseable format.

Cosmic's REST API in Practice

Cosmic's REST API is designed to be fast, predictable, and easy for both humans and AI agents to consume.

Sub-100ms response times globally via CDN caching. Whether it's a developer building a Next.js page or an AI agent fetching content to include in a generated article, the API is consistently fast.

Here's a simple example using the Cosmic TypeScript SDK — which wraps the REST API with full type safety:

import { createBucketClient } from '@cosmicjs/sdk'

const cosmic = createBucketClient({
  bucketSlug: process.env.COSMIC_BUCKET_SLUG as string,
  readKey: process.env.COSMIC_READ_KEY as string,
})

const { objects: posts } = await cosmic.objects
  .find({ type: 'blog-posts' })
  .props(['id', 'title', 'slug', 'metadata.teaser', 'created_at'])
  .sort('-created_at')
  .limit(10)

console.log(posts)

The SDK compiles down to simple REST requests. No schema introspection. No query document compilation. Just a URL, a JSON response, and TypeScript types.

You can also call the REST API directly:

curl "https://api.cosmicjs.com/v3/buckets/my-bucket/objects?type=blog-posts&limit=10&read_key=YOUR_READ_KEY"

That URL is cacheable at the CDN layer, inspectable in a browser, and consumable by any HTTP client — including an AI agent with no Cosmic-specific knowledge whatsoever.

The Decision in Plain Terms

For most content APIs, REST is faster to implement, easier to cache, simpler to debug, and better suited for the AI-agent workflows that are becoming standard in 2026.

GraphQL is the right call when you have complex, client-driven data fetching needs and a team ready to invest in the ecosystem. Those situations exist. But they're not the default.

Cosmic is REST-first because REST is the right default for content delivery — and because in a world where AI agents are increasingly reading and writing your content, the simplicity and cacheability of REST becomes even more valuable, not less.

Start Building with Cosmic

The Cosmic REST API is available on the free plan, no credit card required. Fetch your first objects in under five minutes.

Get started free →

Want to talk through your architecture? Book time with Tony, Cosmic's CEO.

Originally published on the Cosmic blog.

How to Build an AI-Native Team: A Practical Framework for Working Alongside Agents

Tony Spiro — Fri, 08 May 2026 16:04:41 +0000

Cloudflare just published a striking signal. In a letter to their team announcing a workforce reduction of more than 1,100 people, co-founders Matthew Prince and Michelle Zatlyn wrote: "Cloudflare's usage of AI has increased by more than 600% in the last three months alone. Employees across the company, from engineering to HR to finance to marketing, run thousands of AI agent sessions each day to get their work done." They weren't talking about AI tools. They were talking about AI agents. Running autonomously. Integrated into real work. At scale.

Cloudflare's letter makes clear what a lot of business leaders are quietly realizing: the companies that figured out how to work alongside agents aren't just more efficient. They're operating in a fundamentally different mode. The question isn't whether agents are coming to your industry. It's whether your team knows how to work with them when they arrive.

Why Most AI Rollouts Fail

Here's what I see happen at most companies: someone on the leadership team decides it's time to "embrace AI." They buy a handful of tools, maybe subscribe to a few AI writing platforms or coding assistants, send a Slack message encouraging the team to use them, and wait for transformation to happen.

It doesn't happen.

The tools get used occasionally, like a tab you open and forget about. Productivity ticks up slightly, and the team calls it a success. But nothing structurally changes about how work gets done.

The problem isn't the tools. It's that giving your team AI tools is completely different from empowering them to work alongside AI agents. One is autocomplete at scale. The other is a new organizational model.

Most companies are stuck at the tool stage. They're using AI to speed up individual tasks. The teams pulling ahead are building systems where humans and agents execute together, with clear roles, clear handoffs, and clear checkpoints.

This post is a framework for getting there. Everything in it is drawn from how we actually operate at Cosmic. Take what fits your team and apply it directly.

The Framework: How Humans and Agents Execute Together

Before getting into specifics, here's the mental model that shapes everything else:

Agents generate. Humans decide.

Every workflow I've built that works is structured around this principle. Agents handle the volume, the consistency, the first pass, the research, the drafting, the monitoring. Humans handle the judgment calls, the approvals, the external communications, the strategy.

When you try to flip this, or when you skip the human step entirely to move faster, you get burned. I'll share some of the mistakes I made below.

Step 1: Identify Which Work Is Ready to Hand to an Agent

Not everything should go to an agent. The failure mode I see most often is trying to automate work that requires judgment before you've articulated what good judgment looks like.

A useful filter: is this work repeatable, documentable, and reviewable?

Repeatable means it happens on a consistent cadence or follows a consistent pattern.
Documentable means you can write down what good output looks like in enough detail that an agent can match it.
Reviewable means a human can evaluate the output in a reasonable window.

Work involving novel situations, relationship judgment, strategic bets, or creative leaps is not ready for agents yet. Keep humans there.

How to apply this to your team: List the recurring work your team does each week. For each item, ask: could I write instructions clear enough that a smart contractor on day one could produce a good first draft? If yes, that work is ready for an agent.

Step 2: Define Roles, Not Just Tasks

The shift from "AI tools" to "AI-native team" happens when you stop thinking about what AI can help you do and start thinking about what role an agent can own.

At Cosmic, we have agents with defined roles, scopes, and responsibilities:

Mia (Content Agent): Owns the content pipeline. Researches topics, drafts posts, saves them to our CMS as drafts, generates featured images, and pings the team for review.
Marcus (Engineering Agent): Works in our codebase. Can read and write code, create branches, and open pull requests. Scoped to specific repositories, can't deploy to production without an engineer reviewing and merging.
Lisa (Growth Agent): Runs a Monday morning competitor analysis without being asked. Checks what others published or changed, flags keyword gaps, and posts findings to Slack.
Sarah (Outbound): Identifies potential customers and drafts outreach. Connected to our Gmail accounts, composes tailored messages, and sends emails on our behalf after human review.

Giving each agent a real name changed how our team relates to them. Instead of saying "I'll run that through the content tool," someone says "Mia is drafting it." That small shift reinforces the collaborator mindset and makes ownership clearer.

How to apply this to your team: Pick one role that's currently overloaded or understaffed. Write a one-page job description for an AI agent that could own a portion of that work: their responsibilities, their access, their quality bar, and the human checkpoint at the end.

Step 3: Give Agents the Right Context and Access

An agent is only as good as the context it has and the systems it can reach.

A clear role definition. What is this agent responsible for? What is it explicitly not responsible for?
Access to the right systems. Our content agents can read and write objects in Cosmic directly. Without that access, every output has to be manually entered somewhere.
The right information at runtime. An agent running a competitor analysis needs to be able to browse competitor websites, not just work from memory.
A feedback loop. When a human reviews and revises an agent's output, that correction shapes future runs.

Security and access control matter here. Agents should have the minimum access required for their role. Our content agents can write drafts but not publish. Our code agents can open pull requests but not merge to main.

How to apply this to your team: For each agent you're setting up, answer these four questions: (1) What data does it need? (2) What systems does it need access to? (3) What can it never do without human approval? (4) What does success look like?

Step 4: Design the Human-Agent Handoff

The handoff is where most human-AI workflows succeed or fail. Here's the model we've landed on:

Agents draft, humans approve and publish
Agents queue messages, humans review and send
Agents open pull requests, engineers review and merge
Agents surface recommendations, leadership decides

A well-configured agent should hand you a draft that's 70 to 80 percent ready. Your job is the final 20 percent.

A mistake I made early: we shipped an outbound email workflow without proper guardrails. The agent had no instruction to check whether a contact had already been emailed, so several people received the same outreach two or three times. The fix wasn't a smarter model. It was a better review process and tighter instructions.

How to apply this to your team: For each agent workflow, explicitly define the handoff: who reviews, what they're checking for, how they approve or reject, and what happens next. Write it down.

Step 5: Design Workflows Where Humans and Agents Execute in Parallel

The highest-leverage version of this model isn't sequential. It's parallel: humans and agents working on different parts of the same problem simultaneously.

Here's a concrete example from our content workflow:

Lisa monitors competitors and flags keyword gaps every Monday (agent)
I prioritize which topics to pursue that week (human)
Mia drafts posts for the approved topics, generates images, saves to CMS (agent)
I review, revise the final 20 percent, approve (human)
Mia handles scheduling, social copy, and cross-linking (agent)

The result is a content operation run by one human that would take a team of four or five people to run manually.

The Mindset Shift That Makes This Work

Stop thinking of agents as tools and start thinking of them as collaborators with real roles.

A tool mindset says "let me use AI to write this post faster." A collaborator mindset says "Mia owns the first draft of every post; my job is the editorial pass."

Most people use about 10 percent of what agents are capable of. They give agents safe, small tasks and leave most of the capability on the table. Stress-test your agents. Give them harder problems, more context than feels comfortable, more responsibility than you think they can handle. The ceiling is consistently higher than people expect.

The other shift: stop treating agents as executors and start treating them as collaborators in the thinking. When you're about to give an agent a task, try asking what it thinks you should do instead. Ask for three options. Ask what you might be missing. The best outputs I've gotten from agents came not from directives but from dialogue.

Where to Start: A Bottleneck-First Framework

Don't start with a technology roadmap. Start with your biggest bottlenecks.

1. Identify your biggest bottlenecks first. Where is your team slowest? Where does work pile up, stall, or get dropped? That's where agents have the highest ROI.

2. Map the inputs and outputs. Before you touch any tooling, define the task precisely: what does it need to start, and what does done look like? If you can clearly answer both, an agent can own the work between them.

3. Build backwards from the bottleneck. Design the workflow from the desired outcome back to the first action. Ask: what agent handles this, what tools does it need, where are the handoff points, and where do humans need to check the work?

4. Run one workflow for 30 days before adding another. Depth before breadth. Get one workflow actually working and reliable before you build the next one. After 30 days with Mia, our content output had improved enough that we had real capacity to invest in the next workflow.

The Compounding Advantage

Teams building this capability now are accumulating organizational infrastructure that compounds. Every tighter instruction set, every faster review loop, every workflow that shifts from sequential to parallel: these aren't one-time gains. They're the foundation for absorbing whatever capability improvements come next.

You don't have to build everything at once. Start with one workflow, one agent, one handoff. Get that right. Then build on it.

Tony Spiro is the CEO of Cosmic, an AI-powered headless CMS. He writes about building AI-native teams, headless CMS architecture, and the future of content infrastructure.

Originally published on the Cosmic blog.

Build a Blog with Next.js 16 and Cosmic CMS

Tony Spiro — Mon, 04 May 2026 18:52:56 +0000

Next.js 16 shipped in October 2025 with Turbopack stable, React Compiler support, Cache Components, and a redesigned caching model. If you are starting a new blog or content site today, this is the stack to use.

This tutorial walks you through building a production-ready blog from scratch using Next.js 16 and Cosmic as your headless CMS. You will set up a content model in Cosmic, fetch posts with the TypeScript SDK, render them in Next.js 16 App Router server components, and deploy to Vercel.

Estimated time: 30 minutes

What You Will Build

A blog with a homepage listing posts, individual post pages, and tag filtering — all powered by Cosmic's REST API and the TypeScript SDK.

Prerequisites

Node.js 20+
A free Cosmic account (no credit card required)
A Vercel account for deployment (free tier is fine)
Basic familiarity with React and TypeScript

Step 1: Create Your Cosmic Bucket

Log into Cosmic and create a new bucket. Go to Object Types and create a new type called blog-posts. Add the following metafields:

title — Text (built-in)
slug — Text (built-in, auto-generated)
content — Markdown (long-form post body)
excerpt — Textarea (short summary, 160 chars max)
cover_image — File (featured image)
published_date — Date
tags — Text (comma-separated)

Create 2-3 sample blog posts and publish them.

Step 2: Scaffold a Next.js 16 App

npx create-next-app@latest my-blog
cd my-blog

When prompted: use the App Router, TypeScript, and Tailwind CSS.

Install the Cosmic TypeScript SDK

npm install @cosmicjs/sdk

Configure Environment Variables

Create a .env.local file:

COSMIC_BUCKET_SLUG=your-bucket-slug
COSMIC_READ_KEY=your-read-key

Step 3: Create the Cosmic Client

Create lib/cosmic.ts:

import { createBucketClient } from '@cosmicjs/sdk'

export const cosmic = createBucketClient({
  bucketSlug: process.env.COSMIC_BUCKET_SLUG!,
  readKey: process.env.COSMIC_READ_KEY!,
})

Step 4: Define Your TypeScript Types

Create types/post.ts:

export interface Post {
  id: string
  title: string
  slug: string
  metadata: {
    content: string
    excerpt: string
    cover_image: { imgix_url: string }
    published_date: string
    tags: string
  }
}

Step 5: Fetch Posts from Cosmic

Create lib/posts.ts:

import { cosmic } from './cosmic'
import { Post } from '@/types/post'

export async function getPosts(): Promise<Post[]> {
  const { objects } = await cosmic.objects
    .find({ type: 'blog-posts' })
    .props('id,title,slug,metadata')
    .sort('-created_at')
    .status('published')
  return objects as Post[]
}

export async function getPost(slug: string): Promise<Post> {
  const { object } = await cosmic.objects
    .findOne({ type: 'blog-posts', slug })
    .props('id,title,slug,metadata')
    .status('published')
  return object as Post
}

Step 6: Build the Homepage

Replace app/page.tsx:

import { getPosts } from '@/lib/posts'
import Link from 'next/link'
import Image from 'next/image'

export const revalidate = 60

export default async function HomePage() {
  const posts = await getPosts()
  return (
    <main className="max-w-3xl mx-auto py-12 px-4">
      <h1 className="text-4xl font-bold mb-8">Blog</h1>
      <div className="space-y-8">
        {posts.map((post) => (
          <article key={post.id}>
            {post.metadata.cover_image && (
              <Image
                src={`${post.metadata.cover_image.imgix_url}?w=800&auto=format`}
                alt={post.title}
                width={800}
                height={400}
                className="rounded-lg mb-4"
              />
            )}
            <h2 className="text-2xl font-semibold">
              <Link href={`/blog/${post.slug}`}>{post.title}</Link>
            </h2>
            <p className="text-gray-600 mt-2">{post.metadata.excerpt}</p>
          </article>
        ))}
      </div>
    </main>
  )
}

Step 7: Build the Individual Post Page

Create app/blog/[slug]/page.tsx:

import { getPosts, getPost } from '@/lib/posts'
import ReactMarkdown from 'react-markdown'

export async function generateStaticParams() {
  const posts = await getPosts()
  return posts.map((post) => ({ slug: post.slug }))
}

export default async function PostPage({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params  // Next.js 16: params is a Promise
  const post = await getPost(slug)
  return (
    <main className="max-w-3xl mx-auto py-12 px-4">
      <h1 className="text-4xl font-bold mb-8">{post.title}</h1>
      <ReactMarkdown>{post.metadata.content}</ReactMarkdown>
    </main>
  )
}

Important Next.js 16 note: params in dynamic route pages is now a Promise. You must await params before accessing its properties. This is a breaking change from Next.js 14.

Step 8: On-Demand Revalidation

Create app/api/revalidate/route.ts:

import { revalidatePath } from 'next/cache'
import { NextRequest, NextResponse } from 'next/server'

export async function POST(request: NextRequest) {
  const secret = request.headers.get('x-cosmic-secret')
  if (secret !== process.env.COSMIC_WEBHOOK_SECRET) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
  }
  revalidatePath('/blog/[slug]', 'page')
  revalidatePath('/')
  return NextResponse.json({ revalidated: true })
}

In Cosmic, go to Bucket Settings > Webhooks and add a webhook pointing to your /api/revalidate endpoint. Trigger it on publish events.

Step 9: Deploy to Vercel

npx vercel

Or push to GitHub and import at vercel.com. Add your environment variables in Vercel's dashboard.

Step 10: Preview Mode for Drafts (Bonus)

Enable draft previews by setting status: 'any' on the Cosmic client for preview routes. Wire this up to Next.js Draft Mode for a live editor preview experience.

What You Built

Next.js 16 blog with App Router and server components
Content managed in Cosmic (no database required)
Static generation with ISR for fast page loads
On-demand revalidation via webhooks
Automatic image optimization via Cosmic's imgix CDN
Deployed to Vercel in minutes

Why Cosmic for Next.js 16

Sub-100ms API responses — Cosmic's CDN caches content globally, keeping TTFB low at high traffic
Structured content model — your schema maps cleanly to TypeScript interfaces
No backend to maintain — Cosmic handles hosting, scaling, and backups
Free tier to start — 1 bucket, 1,000 objects, 100K cached API requests/month, no credit card required

Next Steps

How We Built AI Agents Into a Headless CMS

Tony Spiro — Tue, 28 Apr 2026 22:13:43 +0000

Most AI features in a CMS are cosmetic. Autocomplete here. A "generate with AI" button there. Useful, sure, but they don't change how teams actually work.

We wanted to go further. We wanted the CMS to have its own team.

This post is a technical walkthrough of how we built four specialized AI agents directly into Cosmic, how they communicate, what they can actually do, and how you can chain them together into fully automated workflows.

The Problem We Were Solving

Every content team we talked to had a version of the same story: someone needed a page updated, a blog post published, or a feature shipped, and it was stuck in a queue. Not because anyone was lazy. Because developer time is finite and content operations compete with product work.

The answer wasn't a better editor. It was removing the dependency entirely.

The Four Agent Types

Cosmic ships with four purpose-built agent types. Each one is optimized for a specific domain.

1. Team Agent

The Team Agent lives in your messaging tools: Slack, WhatsApp, and Telegram. You define its persona, give it a goal, and it communicates with your team like a real colleague. Under the hood, it maintains persistent conversation memory, understands context across sessions, and can trigger actions in the CMS, your codebase, or third-party APIs based on natural language instructions.

Example use case: A content team member messages the agent in Slack: "Write a blog post about our new integration with Vercel and publish it as a draft for review." The Team Agent delegates to the Content Agent, monitors execution, and reports back in the thread.

2. Content Agent

The Content Agent is a CMS-native worker. It can:

Research topics by browsing the web
Generate text, images, and structured content
Create and update CMS objects
Auto-publish or queue content for human review
Run on a schedule or be triggered via webhook

It operates against your existing content models, so it understands your schema, your object types, and your metadata structure.

3. Code Agent

The Code Agent connects to your GitHub repository and can:

Read the full file tree and specific files
Write new features or fix bugs in your codebase
Commit changes to branches
Open pull requests automatically
Respond to code-related tasks described in plain language

This is where things get interesting for developer teams. A PM can say "add a newsletter signup form to the homepage" and the Code Agent will find the right files, write the component, create the content model in Cosmic to save newsletter subscribers, commit it, and open a PR for review.

4. Computer Use Agent

The Computer Use Agent operates a real browser using visual AI. It can:

Navigate websites and interact with UI elements
Record demo videos
Extract structured data from any page
Cross-post media between platforms
Run visual QA on deployed pages
Fill out and submit forms with dynamic input handling
Authenticate into protected areas using secure login flows

This is the agent type that most surprises people. It's not scraping HTML, it's actually looking at the screen and clicking things, the same way a human would.

Chaining Agents Into Workflows

The real power comes when you chain agents together. Cosmic Workflows let you build multi-step automations that run in sequence or parallel, on a schedule or triggered by a webhook.

Here's an example workflow for launching an e-commerce site:

Traditional timeline for this: 2 to 3 weeks. With Cosmic Workflows: approximately 20 minutes.

The Technical Architecture

A few implementation details worth knowing:

REST API. All agent interactions with the CMS go through Cosmic's REST API, which returns responses in under 100ms. The TypeScript SDK wraps the API cleanly, and the CLI and MCP Server give agents additional surfaces to work with.

Framework-agnostic. The agents don't care what frontend you're using. They've been tested against Next.js, React, Vue, Nuxt, Astro, Remix, and Svelte.

Scheduling and webhooks. Content Agents and Workflows can be set to run on a cron schedule or triggered via incoming webhook. This means you can wire them into any external event: a new Stripe payment, a GitHub push, a form submission.

Memory modes. Team Agents support both session memory (reset per conversation) and persistent memory (retained across all conversations). Persistent memory is what makes a Team Agent feel like an actual team member over time.

What This Looks Like In Practice

FINN, the car subscription platform, has been using Cosmic to reduce their dependency on developer time for content changes. Their co-founder put it clearly:

"Cosmic is: us never having to ask a developer to change anything on the backend of our website." - Maximilian Wuhr, Co-Founder at FINN

With agents, that same principle extends to code, QA, and content operations, running autonomously around the clock.

Getting Started

Cosmic is free to start, no credit card required.

Free: $0/month - 1 Bucket, 2 team members, 1,000 Objects
Builder: $49/month - 2 Buckets, 3 team members, 5,000 Objects
Team: $299/month - 3 Buckets, 5 team members, 20,000 Objects
Business: $499/month - 5 Buckets, 10 team members, 50,000 Objects

You can explore the agents and workflows at cosmicjs.com/ai. If you want to talk through what this could look like for your specific stack, book a quick call with Tony.

Cosmic Agents vs Sanity Agent Context vs Hygraph AI: A Real Comparison

Tony Spiro — Mon, 27 Apr 2026 18:25:04 +0000

The phrase "AI-powered CMS" has become meaningless. Every headless CMS vendor is using it. The real question is: what does the AI actually do?

Cosmic, Sanity, and Hygraph are three of the most actively developed headless CMS platforms in 2026. All three are investing in AI. But their approaches are categorically different, and the distinction matters for how you build.

This comparison looks at what each platform's AI actually does, where it stops, and which approach fits what kind of team.

What We're Comparing

Cosmic: Four distinct agent types (Team, Content, Code, Computer Use) that operate across your entire stack
Sanity Agent Context: A structured content delivery layer for external AI agents, plus the Content Agent for content operations
Hygraph: AI-assisted content features (generation, translation, enrichment) built into the editorial workflow, with no native agent product

These are not equivalent products doing the same thing at different price points. They represent three distinct philosophies about where AI belongs in a content platform.

Cosmic: Agents That Work Across Your Stack

Cosmic ships four agent types that operate at different layers of your development workflow:

Team Agents

Live in Slack, WhatsApp, and Telegram. They have persistent memory, custom personas, and configurable goals. A Team Agent can be your content lead, a growth assistant, a support agent, or anything else your team needs. They participate in your actual communication channels, receive messages, respond to them, and maintain context across conversations.

Content Agents

Generate and manage CMS content: blog posts, landing pages, AI images, AI video. They run on schedules, respond to webhooks, and chain into multi-step workflows. A Content Agent can publish a weekly roundup, generate product descriptions at scale, or update metadata across hundreds of objects.

Code Agents

Connect directly to GitHub repositories. They create branches, commit code, build features, fix bugs, and open pull requests. A Code Agent can receive a feature request in Slack and deliver a working pull request to your repository. This is not a content tool. It is a software development tool built into a CMS platform.

Computer Use Agents

Control browsers using visual AI. They record demo videos, extract data from web pages, cross-post media, and automate any browser-based workflow.

All four agent types chain together in Workflows. A single workflow can: generate content with a Content Agent, build a feature in GitHub with a Code Agent, and test the result with a Computer Use Agent.

The key distinction: Cosmic agents are not features inside a CMS dashboard. They are autonomous team members that operate across your content, codebase, and communication channels.

Sanity: Agent Context + Content Agent

Sanity's AI story has two distinct parts worth separating.

Agent Context

Agent Context is Sanity's framework for making your CMS content available to external AI agents via MCP. It provides semantic search, GROQ + semantic query combination, editorial access controls, and real-time sync.

Agent Context is infrastructure for other people's agents to use your Sanity content. It is not Sanity building agents that act on your behalf.

Content Agent

Sanity's Content Agent is focused on content operations inside the CMS: bulk edits across thousands of documents, content audits, bulk replace across large document sets, and web search to identify content gaps.

The scope: Sanity's Content Agent stays inside the CMS. It does not write application code, touch your GitHub repository, create branches, open pull requests, or deploy software.

Hygraph: AI Features, Not AI Agents

Hygraph offers AI-assisted content features built into the editorial and content operations workflow. There is no dedicated Hygraph AI agent product.

What Hygraph does with AI:

Content enhancement: AI writing assistance, SEO optimization, metadata generation
Translation and localization: AI-powered translation with integrations like DeepL
Workflow automation: AI enrichment triggered by content changes via Agent Actions
Content auditing: Find stale pages, missing metadata, terminology drift
Federation: Query distributed content sources in real time

What Hygraph does not have:

Native AI agents that act autonomously on your behalf
Code agents that work in GitHub
Team agents that live in Slack or messaging channels
Multi-agent workflows that chain content, code, and browser automation

Side-by-Side: What Each Platform's AI Actually Does

Cosmic

Team agents in Slack, WhatsApp, Telegram: Yes
Content generation and management agents: Yes
Code agents (GitHub branches, PRs, commits): Yes
Computer Use / browser automation agents: Yes
Multi-agent chained Workflows: Yes
MCP Server: Yes (17 tools)
Agent Skills for Cursor, Claude Code, Copilot: Yes (16+ integrations)
Bulk content operations via AI: Yes
AI image generation: Yes
AI video generation: Yes

Sanity

Team agents in messaging channels: Slack only (via Content Agent)
Content generation and management agents: Yes (Content Agent)
Code agents (GitHub branches, PRs, commits): No
Computer Use / browser automation agents: No
Multi-agent chained Workflows: No
MCP Server: Yes
Bulk content operations via AI: Yes (Content Agent's core strength)
AI image generation: Yes (via Content Agent)
AI video generation: No
Structured content delivery for external agents (Agent Context): Yes

Hygraph

Team agents in messaging channels: No
Content generation and management agents: No (AI-assisted features, not agents)
Code agents (GitHub branches, PRs, commits): No
Computer Use / browser automation agents: No
Multi-agent chained Workflows: No
MCP Server: No dedicated product
Bulk content operations via AI: Yes (via Agent Actions, event-driven)
AI translation (field-by-field): Yes
AI content auditing: Yes
Content federation for AI use cases: Yes (a genuine differentiator)

The Practical Question: What Layer Do You Need AI to Operate In?

Choose Cosmic if:

You want AI that operates across your full stack: content, code, browser, and communication channels
Your team needs Code Agents creating branches and opening pull requests automatically
You want AI team members living in Slack, WhatsApp, or Telegram with persistent memory
Multi-agent Workflows that chain content generation, code deployment, and browser testing matter to you
You use Cursor, Claude Code, or GitHub Copilot and want your CMS context built into your IDE's AI assistant

Choose Sanity if:

Your primary AI use case is managing large volumes of existing content through conversation
You need bulk editing, content audits, and gap analysis across thousands of documents
Your team is editorial-first and the bottleneck is content operations, not engineering

Choose Hygraph if:

Your priority is AI-assisted content workflows inside a governed, enterprise content platform
Federation across distributed content sources is a real architectural need
You need field-level AI translation with schema integrity for a global content operation
You prefer AI that stays in an assisted, human-reviewed loop

Pricing Comparison (Verified April 2026)

Cosmic

Free: $0/month, 1 Bucket, 2 Team members, 1,000 Objects, 1 Team agent
Builder: $49/month, 2 Buckets, 3 Team members, 5,000 Objects, 3 Team agents
Team: $299/month, 3 Buckets, 5 Team members, 20,000 Objects, 10 Team agents
Business: $499/month, 5 Buckets, 10 Team members, 50,000 Objects, 25 Team agents
Additional users: $29/user/month
Free plan is genuinely free forever, no credit card required

Sanity

Free: $0/month, up to 20 seats, 10,000 documents
Growth: $15/seat/month, up to 50 seats, 25,000 documents
Enterprise: Custom
Notable: Dedicated support is a $799/month add-on. SSO is $1,399/month.

Hygraph

Free tier available
Scale and Enterprise tiers (contact for pricing)
Federation and advanced AI features are enterprise-tier

The Deeper Distinction: Infrastructure vs. Agents

Sanity's Agent Context takes a real infrastructure play: instead of building agents, they are making Sanity the best content source for whatever agents you or your users are building.

Cosmic's bet is different. The agents are not features on top of the CMS. They are the product. Cosmic's position is that the CMS of 2026 is not a place where humans store content and developers build on top of it. It is an agentic platform where AI team members participate in the full development and content lifecycle.

As FINN co-founder Maximilian Wuhr put it: "Cosmic is: us never having to ask a developer to change anything on the backend of our website."

That is one version of what agents unlock. The ceiling is much higher.

Frequently Asked Questions

Does Hygraph have AI agents?
Not in the autonomous sense. Hygraph offers AI-assisted content features and event-driven AI enrichment via Agent Actions. There is no Hygraph agent that acts independently across your stack.

What is Sanity Agent Context?
Agent Context is Sanity's infrastructure layer that makes your Sanity content available to external AI agents via MCP. It is not Sanity building agents on your behalf.

Can Cosmic agents write code?
Yes. Cosmic Code Agents connect to GitHub repositories, create branches, commit changes, and open pull requests. This is one of the core distinctions from both Sanity's and Hygraph's AI offerings.

Is Cosmic free?
Yes. Cosmic's Free plan is $0/month forever, no credit card required. It includes 1 Bucket, 2 Team members, 1,000 Objects, and 1 Team agent.

Ready to See Cosmic Agents in Action?

Why Headless CMS Is the Wrong Category

Tony Spiro — Sun, 26 Apr 2026 23:17:54 +0000

The term "headless CMS" made sense in 2015. It was a genuine breakthrough: decouple your content from your presentation layer, expose it through an API, and let developers build whatever frontend they wanted. It solved a real problem.

In 2026, calling a platform like Cosmic a "headless CMS" is like calling Vercel a "file host." Technically not wrong. Strategically, completely wrong.

The category has moved. The label hasn't. It's time to name what comes next.

1. The Original Headless CMS Promise (And Why It Was Right for Its Time)

Around 2013 to 2016, the web development world hit a wall. WordPress powered a third of the internet, but it also chained content to PHP templates and a rigid frontend. Enterprise teams were stuck in Sitecore and Adobe Experience Manager, paying six-figure licensing fees for systems that required specialists just to publish a blog post.

Headless CMS changed the contract. Content lived in a structured repository, accessible via API. Developers could build frontends in React, Vue, Angular, or anything else they chose. Content teams could work independently in a clean editor. The decoupling was real and valuable.

Platforms like Contentful (founded 2013) and later Sanity, Storyblok, and Prismic built strong businesses on this premise. The market validated them. According to Grand View Research, the headless CMS market is worth $2 to $4 billion today and is projected to grow to $6 billion or more by 2033.

The problem is not that headless CMS failed. The problem is that it succeeded, and then the world kept moving.

2. What Developer Teams Actually Need in 2026

Talk to any engineering lead at a modern product company and ask them what they need from their content infrastructure. You will not hear "a better API for structured content." You will hear something like this:

We need our marketing team to launch new landing pages without filing a Jira ticket.
We need our AI agents to be able to read and write content programmatically.
We need our content workflows to trigger downstream actions: Slack notifications, data syncs, deployment pipelines.
We need our editors to work in Slack or WhatsApp, not a separate dashboard.
We need our platform to handle the full lifecycle: create, publish, personalize, and retire content.

This is not a content management problem. It is a content infrastructure problem. And content infrastructure in 2026 looks nothing like a headless CMS from 2016.

The broader composable content and modern CMS market is estimated at $10 to $25 billion by MarketsandMarkets. Teams that limit their thinking to "headless CMS" are scoping themselves into a shrinking corner of a much larger map.

3. The Category Convergence Happening Right Now

Something interesting is happening across the developer tools landscape. The clean category lines that existed five years ago are dissolving.

CMS platforms are becoming dev platforms. Contentful launched an app framework. Sanity built a structured content operating system. Storyblok added visual editing.
Dev platforms are becoming content platforms. Vercel launched CMS integrations. Netlify acquired multiple CMS products. Cloudflare Pages added content workflows.
AI tooling is collapsing into both. Large language models need structured content to stay grounded. AI agents need APIs to read and write content programmatically.

The result: every serious platform is building toward the same destination. The companies that still describe themselves primarily by their 2016 category name are telling you something about their product roadmap thinking.

4. Why the Wrong Category Label Is Costing Teams Money and Time

This is not just a semantics debate. Category labels drive buying decisions, and wrong labels create wrong criteria.

When a CTO goes to evaluate a "headless CMS," they bring a headless CMS checklist: API performance, content modeling flexibility, editor experience, pricing per seat. Legitimate criteria. But incomplete for 2026.

They are not asking:

Can AI agents in my team's Slack channel query and update this content without a human in the loop?
Can I build a full internal tool or customer-facing app on this platform, not just a marketing site?
Does this platform have an MCP Server so tools like Claude Code and Cursor can work directly with my content?
Can I extend the platform with Agent Skills, so my editors can trigger complex workflows from a chat interface?

When teams do not ask these questions, they end up buying a headless CMS and then separately buying an AI platform, a workflow tool, an internal tooling framework, and a handful of Zapier integrations to stitch it all together. The category label caused them to under-scope the problem.

5. What the New Category Looks Like

The new category does not have a consensus name yet. Here is what it includes:

Content infrastructure. Structured content models, a fast REST API and TypeScript SDK, global CDN delivery, media management. The table stakes headless CMS established. Still necessary, but no longer sufficient.

AI-native agents. Not AI bolted on top of a content editor. AI agents that are first-class members of your team. They live in Slack, WhatsApp, and Telegram. They can read content, write content, trigger workflows, and respond to natural language requests. They operate on schedules or respond to events.

Workflow automation. Multi-step automated processes that chain content operations, approvals, notifications, and external API calls into coherent pipelines. Native workflow execution, not a third-party integration layer.

Developer-first extensibility. An MCP Server that lets AI coding tools like Claude Code and Cursor interact directly with your content infrastructure. Agent Skills that make content operations available as composable building blocks for any AI assistant.

App platform capabilities. The ability to build not just content-driven websites but full applications on the same infrastructure. Content becomes data. The CMS becomes the backend.

This is not a feature list. It is a different mental model for what a content platform is.

6. Where Cosmic Fits in the New Map

Cosmic (YC W19) started as a headless CMS. It has the API performance, the content modeling, and the editor experience that enterprises require. Companies like FINN, Tripwire Interactive, Parque Explora, and Vuetify chose it and stayed because the fundamentals are solid.

FINN's co-founder Maximilian Wuhr put it directly: "Cosmic is: us never having to ask a developer to change anything on the backend of our website."

That outcome, non-technical teams operating independently, is the original headless CMS promise fulfilled.

But Cosmic has not stopped there. Today, Cosmic is an AI-powered content and app platform:

AI Agents in Slack, WhatsApp, and Telegram. Editors can request content, trigger updates, and get summaries without leaving their messaging app.
Workflows. Multi-step automated pipelines that orchestrate content operations, approvals, and integrations.
MCP Server. AI coding tools like Claude Code and Cursor can interact directly with your content.
Agent Skills for Cursor and Claude Code. Composable content operations available natively to the AI tools your developers already use.
REST API and TypeScript SDK. Battle-tested, fast, and developer-friendly.

The market segment Cosmic competes in is not a $4 billion headless CMS market. It is a $25 billion-plus content infrastructure and AI-powered app platform market.

Calling it a headless CMS is like calling Vercel a file host. Accurate at the edges. Completely wrong about what it is.

The category will be named. We're naming it now.

An Agentic Content Platform is not a headless CMS with AI bolted on. It is a platform where AI agents are first-class participants in every content operation: writing, editing, publishing, coding, deploying, measuring.

The companies that recognize this shift early will stop evaluating "headless CMS vendors" and start asking a different question: which platform lets my team move fastest when humans and agents are working together?

That is the question Cosmic is built to answer.

Ready to see what AI-powered content infrastructure looks like? Start free on Cosmic or book a demo to talk through what your stack could look like.

How to Migrate from Storyblok to Cosmic

Tony Spiro — Sun, 26 Apr 2026 23:11:31 +0000

A step-by-step guide for developers migrating from Storyblok to Cosmic: content model mapping, component-to-metafield conversion, media migration, API migration, and webhooks — with real TypeScript code examples.

Why Developers Are Migrating from Storyblok to Cosmic

Storyblok was a smart choice for teams who wanted a visual editor baked into their CMS. But as applications grow in complexity and AI becomes central to content operations, its limitations become harder to work around. Three pain points keep coming up in migration conversations:

Visual editor lock-in. Storyblok components are built around page presentation, which couples your content model to your frontend. When you need to reuse content across channels, that coupling becomes a bottleneck.

Pricing pressure. Seat fees, delivery limits, and add-on costs compound as teams grow. Budgeting for Storyblok at scale is unpredictable.

No native AI. Adding AI to a Storyblok workflow requires third-party integrations and significant custom engineering. Cosmic has AI Agents built in.

If any of those sound familiar, this guide will walk you through the full migration process: content model mapping, component-to-metafield conversion, media migration, API migration, and webhooks.

Before You Start: Understanding the Key Differences

Storyblok Concept	Cosmic Equivalent
Story	Object
Component/Block	Object Type + Metafields
Component Field	Metafield
Space	Bucket
Asset	Media
Datasource	Object Type (for structured reference data)
Webhook	Webhook (via add-on)

The most important conceptual shift: Storyblok organizes content around components on stories. Cosmic organizes content around Objects of a given Object Type. The result is more flexible — you're not constrained by what a visual editor can preview.

Step 1: Map Your Content Model

Start by auditing your Storyblok components. For each component, you'll create a corresponding Object Type in Cosmic with the right Metafields.

Field type mapping reference:

Storyblok richtext → Cosmic html-textarea or markdown
Storyblok asset → Cosmic file
Storyblok text → Cosmic text
Storyblok textarea → Cosmic textarea
Storyblok single select → Cosmic select
Storyblok multi select → Cosmic multi-select
Storyblok nested blocks → Cosmic relationship field or objects
Storyblok reference → Cosmic relationship field (object)

Step 2: Export Your Content from Storyblok

Use the Storyblok Management API to export your stories. You'll need your Storyblok API token.

const response = await fetch(
  `https://mapi.storyblok.com/v1/spaces/${SPACE_ID}/stories`,
  {
    headers: {
      Authorization: STORYBLOK_MANAGEMENT_TOKEN,
    },
  }
);
const { stories } = await response.json();

Step 3: Migrate Media Assets

Before importing content objects, migrate your media. Storyblok stores assets on their CDN; you'll need to re-upload them to Cosmic's media library.

import { createBucketClient } from '@cosmicjs/sdk';

const cosmic = createBucketClient({
  bucketSlug: process.env.COSMIC_BUCKET_SLUG,
  readKey: process.env.COSMIC_READ_KEY,
  writeKey: process.env.COSMIC_WRITE_KEY,
});

async function migrateAsset(storyblokUrl: string, filename: string) {
  const response = await fetch(storyblokUrl);
  const buffer = await response.arrayBuffer();
  const file = new File([buffer], filename);

  const { media } = await cosmic.media.insertOne({ media: file });
  return media.imgix_url;
}

Step 4: Import Content to Cosmic

With your content model mapped and media migrated, import your stories as Cosmic Objects using the JavaScript/TypeScript SDK.

async function importStory(story: StoryblokStory, mediaMap: Record<string, string>) {
  await cosmic.objects.insertOne({
    title: story.name,
    type: 'your-object-type-slug',
    status: story.published ? 'published' : 'draft',
    metadata: {
      content: story.content.body,
      image: mediaMap[story.content.image?.filename] || '',
      // map other fields as needed
    },
  });
}

Step 5: Update Your API Calls

Storyblok and Cosmic have different API patterns. Here's how to update your frontend code.

Before (Storyblok):

import { storyblokInit, apiPlugin } from '@storyblok/react';

storyblokInit({
  accessToken: process.env.STORYBLOK_TOKEN,
  use: [apiPlugin],
});

const { data } = await storyblokApi.get('cdn/stories', {
  version: 'published',
});

After (Cosmic):

import { createBucketClient } from '@cosmicjs/sdk';

const cosmic = createBucketClient({
  bucketSlug: process.env.COSMIC_BUCKET_SLUG,
  readKey: process.env.COSMIC_READ_KEY,
});

const { objects } = await cosmic.objects.find({
  type: 'your-object-type-slug',
}).props('id,title,slug,metadata');

Important: Cosmic uses the REST API only. There is no GraphQL endpoint.

Step 6: Migrate Webhooks

If you use Storyblok webhooks to trigger builds or revalidation, you'll need to set up Cosmic webhooks. Cosmic webhooks are available as an add-on ($99/month, or included in the $199/month bundle). Once enabled, configure them in the Cosmic dashboard under Settings > Webhooks.

Migration Checklist

Content Model

[ ] Audit all Storyblok components and fields
[ ] Create corresponding Object Types in Cosmic dashboard
[ ] Map all field types (richtext → markdown, asset → file, etc.)
[ ] Test Object Type schemas with sample content

Media

[ ] Export list of all Storyblok assets
[ ] Run media migration script
[ ] Verify asset URLs in Cosmic media library
[ ] Build asset URL map for content import

Content

[ ] Export all Storyblok stories via Management API
[ ] Run content import script
[ ] Verify published/draft status is correct
[ ] Spot-check content in Cosmic dashboard

API Integration

[ ] Replace Storyblok SDK imports with Cosmic SDK
[ ] Update all API calls to use Cosmic REST API
[ ] Update environment variables
[ ] Test all content queries in development

Webhooks and Automation

[ ] Recreate Storyblok webhooks in Cosmic
[ ] Update webhook endpoints in your applications
[ ] Test build triggers and cache revalidation

Go Live

[ ] Run full content audit comparing Storyblok and Cosmic
[ ] Update DNS / CDN configuration if needed
[ ] Monitor error rates after launch
[ ] Deprecate Storyblok account once migration is confirmed

Supported Frameworks

Cosmic works with all major JavaScript frameworks:

Next.js — Full support including App Router and Pages Router
React — Works with any React setup
Vue — Full compatibility
Nuxt — Server-side rendering and static generation
Astro — Content collections and SSR
Remix — Loader-based data fetching
Svelte / SvelteKit — Full support
Gatsby — Static generation

The Cosmic JavaScript/TypeScript SDK works in any Node.js environment and in modern browsers.

This article was originally published on the Cosmic blog.

Headless CMS for TanStack Start: Build a Blog with Cosmic

Tony Spiro — Sat, 18 Apr 2026 19:08:53 +0000

You want SSR, fast routing, and a CMS your whole team can edit without touching code. Here's how to build that stack in under an hour.

TanStack Start pairs naturally with Cosmic: Start handles full-document SSR, streaming, and type-safe routing via Vite and TanStack Router, while Cosmic gives you a structured, API-first content layer your editors can use without a developer in the room. The result is a modern content stack that's fast to build, easy to maintain, and genuinely pleasant to work with.

This tutorial walks through building a content-driven TanStack Start blog powered by Cosmic. You'll fetch posts from Cosmic using the JavaScript SDK, render them with server functions, and have a working SSR blog in under 30 minutes.

Prerequisites

Node.js 18 or later
A free Cosmic account with a bucket set up
Basic familiarity with React and TypeScript

1. Create a TanStack Start Project

The fastest way to scaffold a new project is with the TanStack CLI:

npx create-tsrouter-app@latest my-cosmic-app --template start-basic
cd my-cosmic-app
npm install

This gives you a working TanStack Start app with file-based routing, SSR enabled, and Vite as the bundler.

2. Install the Cosmic SDK

npm install @cosmicjs/sdk

3. Configure Your Environment Variables

Create a .env file at the root of your project:

COSMIC_BUCKET_SLUG=your-bucket-slug
COSMIC_READ_KEY=your-read-key

You can find both values in your Cosmic dashboard under Bucket > Settings > API Keys.

TanStack Start uses Vite under the hood. Server-side environment variables are accessed via process.env inside server functions. For client-side access, prefix with VITE_ — but keep your read key on the server only.

4. Create a Cosmic Client

Add a shared client file at src/lib/cosmic.ts:

import { createBucketClient } from '@cosmicjs/sdk'

export const cosmic = createBucketClient({
  bucketSlug: process.env.COSMIC_BUCKET_SLUG!,
  readKey: process.env.COSMIC_READ_KEY!,
})

5. Fetch Posts with a Server Function

TanStack Start's server functions run exclusively on the server, making them the right place to call external APIs and keep keys out of the client bundle.

Create src/server/posts.ts:

import { createServerFn } from '@tanstack/start'
import { cosmic } from '../lib/cosmic'

export type Post = {
  id: string
  title: string
  slug: string
  metadata: {
    teaser: string
    published_date: string
    image?: { imgix_url: string }
  }
}

export const fetchPosts = createServerFn({ method: 'GET' }).handler(
  async () => {
    const { objects } = await cosmic.objects
      .find({ type: 'blog-posts' })
      .props(['id', 'title', 'slug', 'metadata.teaser', 'metadata.published_date', 'metadata.image'])
      .limit(10)

    return objects as Post[]
  }
)

export const fetchPost = createServerFn({ method: 'GET' })
  .validator((slug: string) => slug)
  .handler(async ({ data: slug }) => {
    const { object } = await cosmic.objects
      .findOne({ type: 'blog-posts', slug })
      .props(['id', 'title', 'slug', 'metadata'])
      .depth(1)

    return object
  })

6. Create the Blog Index Route

TanStack Start uses file-based routing. Create src/routes/blog/index.tsx:

import { createFileRoute, Link } from '@tanstack/react-router'
import { fetchPosts } from '../../server/posts'

export const Route = createFileRoute('/blog/')({
  loader: () => fetchPosts(),
  component: BlogIndex,
})

function BlogIndex() {
  const posts = Route.useLoaderData()

  return (
    <main className="max-w-2xl mx-auto py-12 px-4">
      <h1 className="text-3xl font-bold mb-8">Blog</h1>
      <ul className="space-y-6">
        {posts.map((post) => (
          <li key={post.id}>
            <Link
              to="/blog/$slug"
              params={{ slug: post.slug }}
              className="group"
            >
              <h2 className="text-xl font-semibold group-hover:underline">
                {post.title}
              </h2>
              {post.metadata.teaser && (
                <p className="text-gray-600 mt-1">{post.metadata.teaser}</p>
              )}
              {post.metadata.published_date && (
                <time className="text-sm text-gray-400">
                  {new Date(post.metadata.published_date).toLocaleDateString()}
                </time>
              )}
            </Link>
          </li>
        ))}
      </ul>
    </main>
  )
}

7. Create the Post Detail Route

Install react-markdown for safe, component-based markdown rendering:

npm install react-markdown

Create src/routes/blog/$slug.tsx:

import { createFileRoute, notFound } from '@tanstack/react-router'
import ReactMarkdown from 'react-markdown'
import { fetchPost } from '../../server/posts'

export const Route = createFileRoute('/blog/$slug')({
  loader: async ({ params }) => {
    const post = await fetchPost({ data: params.slug })
    if (!post) throw notFound()
    return post
  },
  component: BlogPost,
})

function BlogPost() {
  const post = Route.useLoaderData()

  return (
    <main className="max-w-2xl mx-auto py-12 px-4">
      {post.metadata.image?.imgix_url && (
        <img
          src={`${post.metadata.image.imgix_url}?w=800&auto=format`}
          alt={post.title}
          className="w-full rounded-lg mb-8"
        />
      )}
      <h1 className="text-3xl font-bold mb-4">{post.title}</h1>
      {post.metadata.published_date && (
        <time className="text-sm text-gray-400 block mb-8">
          {new Date(post.metadata.published_date).toLocaleDateString()}
        </time>
      )}
      <div className="prose">
        <ReactMarkdown>{post.metadata.markdown_content || ''}</ReactMarkdown>
      </div>
    </main>
  )
}

8. Run the Dev Server

npm run dev

Open http://localhost:3000/blog and you should see your Cosmic posts rendered server-side via TanStack Start.

Deploy to Vercel

TanStack Start supports Vercel out of the box. From the project root:

npm install -g vercel
vercel

Add your environment variables in the Vercel dashboard under Project > Settings > Environment Variables:

COSMIC_BUCKET_SLUG
COSMIC_READ_KEY

Deploy and you're live.

What to Build Next

Localization: Cosmic's Localization add-on lets you manage content in multiple languages from the same bucket. Add a locale param to your SDK calls and TanStack Router handles the rest.
Webhooks: Trigger a Vercel redeploy automatically when editors publish new content in Cosmic. Set up a webhook in Cosmic pointing to your Vercel deploy hook URL.
Team Agent in Slack: Install a Cosmic Team Agent in your Slack workspace. Editors can publish, update, and query content from Slack without opening the dashboard.
Full-text search: Use the Cosmic REST API with a ?query= parameter to add search to your TanStack Start app without a separate search service.

Cosmic is an AI-powered headless CMS with a REST API, TypeScript SDK, and AI agents that live in Slack, WhatsApp, and Telegram. Start for free.