DEV Community

Tony Spiro
Tony Spiro

Posted on • Originally published at cosmicjs.com

Connect Claude to Your CMS: A 5-Minute Guide to the Cosmic MCP Server

#ai #mcp #cms #typescript

If you already run Claude every day, the next obvious question is whether it can touch your content. Not summarize it. Not draft copy in a chat window you then paste somewhere. Actually read your content model, query it, and write back to it.

Cosmic answers that with an MCP server. This guide gets you connected in about five minutes, then covers the part most people skip: what Claude is allowed to do once it is connected.

What MCP actually gives you

Model Context Protocol is a standard way for an AI client to discover and call tools. Instead of you describing your CMS to Claude in prose, Claude asks the server what tools exist and calls them directly.

The Cosmic MCP server exposes 18 bucket-scoped tools. They cover objects, object types, media, and AI generation. Bucket-scoped is the important word: the server operates against one Bucket, using the keys you give it, and it cannot reach across your other Buckets.

The five-minute setup

1. Get your Bucket keys

In your Cosmic dashboard, open your Bucket, then Settings > API Access. Copy three things: your Bucket slug, your read key, and your write key. The keys are separate on purpose, and that separation is the single most useful control in this whole setup. More on that below.

2. Add the server to your MCP client config

The hosted endpoint is the fastest path and needs no install. Point your client at https://mcp.cosmicjs.com/v1/buckets/{your-bucket-slug} and authenticate with your keys in the Authorization header.

For Claude Desktop, edit your config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json 
{
  "mcpServers": {
    "cosmic": {
      "url": "https://mcp.cosmicjs.com/v1/buckets/your-bucket-slug",
      "headers": {
        "Authorization": "Bearer your-read-key:your-write-key"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Cursor takes the same shape in .cursor/mcp.json for a single project, or ~/.cursor/mcp.json globally.

Read the bearer token carefully: read key, colon, write key. Drop the :your-write-key suffix and the connection becomes read-only. Hold onto that detail, because it is the control worth understanding before you point any of this at production.

If you would rather run the MCP process inside your own dev environment, the @cosmicjs/mcp package ships a stdio binary that reads credentials from environment variables:

{
  "mcpServers": {
    "cosmic": {
      "command": "npx",
      "args": ["@cosmicjs/mcp"],
      "env": {
        "COSMIC_BUCKET_SLUG": "your-bucket-slug",
        "COSMIC_READ_KEY": "your-read-key",
        "COSMIC_WRITE_KEY": "your-write-key"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Save the file and restart the client. The Cosmic tools show up in the tool list.

3. Verify the connection

Ask Claude something read-only first:

"List the object types in this Bucket and tell me how many objects are in each."

If you get back your real content model, you are connected. If you get nothing, the key or the Bucket slug is wrong, and the error message will say which.

4. Try a real task

Once reads work, the useful prompts look like this:

"Find every published blog post missing an SEO description and list the slugs."

"Create a draft post from this outline, set the author to Tony Spiro, and leave status as draft."

"Add alt text to every image in the media library that does not have any."

That last one is the kind of chore that never gets done manually and takes an agent about a minute.

The control that matters: read keys and write keys

Here is the part worth understanding before you hand an agent your production Bucket.

Cosmic issues separate read and write keys. Give an MCP client a read-only key and it gets the read tools only. Every write tool returns a clear blocked error. Nothing is guessed, nothing is inferred from a system prompt, and no amount of clever prompting talks its way past it.

You can verify this yourself in under a minute:

  1. Set the Authorization header to Bearer your-read-key with no write key and no colon
  2. Ask Claude to create a new object
  3. Read the blocked error it returns

That is a checkable guardrail, not a policy document. It is also the honest starting posture for anyone connecting an agent to real content: read-only first, then widen scope deliberately once you trust the workflow.

When you are ready for writes, the safe pattern is a write-enabled key pointed at a staging Bucket, with the production Bucket still read-only. Cosmic plans include multiple Buckets from Builder up, so a dedicated staging Bucket for agent work is a reasonable setup rather than an exotic one.

Writing content through the API instead

If you would rather script the workflow than chat it, the TypeScript SDK covers the same ground:

npm install @cosmicjs/sdk
Enter fullscreen mode Exit fullscreen mode 
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!,
});

// Read: find drafts with no SEO description
const { objects: posts } = await cosmic.objects
  .find({ type: 'blog-posts', status: 'draft' })
  .props('id,title,slug,metadata.seo_description');

const missing = posts.filter((p) => !p.metadata?.seo_description);

// Write: patch one of them
await cosmic.objects.updateOne(missing[0].id, {
  metadata: {
    seo_description: 'A short, specific summary under 155 characters.',
  },
});
Enter fullscreen mode Exit fullscreen mode

Note that writeKey is a separate argument from readKey. Omit it and every write call fails, which is the same guardrail the MCP server relies on.

What this is good for, and what it is not

Good fits today:

  • Content audits: missing metadata, broken internal links, stale dates, orphaned objects
  • Bulk mechanical edits: alt text, SEO descriptions, tag normalization, category cleanup
  • Draft generation against your real content model, so the shape is correct on the first pass
  • Answering questions about your own content library without opening the dashboard

Not a good fit yet:

  • Unsupervised publishing to production. Keep a human on the publish step.
  • Anything where a wrong write is expensive and hard to reverse.

The practical rule: let the agent do the reading and the drafting, and keep the irreversible actions behind a person.

Frequently asked questions

Do I need a paid plan to use the MCP server?
You can start on the Free plan, which includes 1 Bucket, 2 team members, and 1,000 Objects. If you want a separate staging Bucket for agent writes, that starts at the Builder plan ($49/month, 2 Buckets, 3 team members, 5,000 Objects).

Does Cosmic offer a GraphQL endpoint for this?
No. Cosmic offers a REST API and the JavaScript/TypeScript SDK. The MCP server sits on top of the same REST API.

Can I limit which object types an agent can touch?
The key-level control is read versus write. For tighter scoping, point the agent at a Bucket that only contains the content you want it to work on.

Does this work with clients other than Claude?
MCP is a client-agnostic standard, so any MCP-compatible client can connect to the same server with the same 18 tools. Cursor is covered above, and the hosted endpoint speaks the streamable-HTTP transport that other clients use.

Try it on a real Bucket

The fastest way to understand what an agent can do with a proper content model behind it is to connect one and ask it a question about your own content.

Cosmic is a YC W19 company building the content layer for teams that want their AI tools to work against real, structured content instead of copy pasted into a chat box.

Top comments (0)