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.
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.
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.
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:
~/Library/Application Support/Claude/claude_desktop_config.json
%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"
}
}
}
}
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"
}
}
}
}
Save the file and restart the client. The Cosmic tools show up in the tool list.
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.
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.
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:
Authorization
header to Bearer your-read-key
with no write key and no colonThat 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.
If you would rather script the workflow than chat it, the TypeScript SDK covers the same ground:
npm install @cosmicjs/sdk
js
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.',
},
});
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.
Good fits today:
Not a good fit yet:
The practical rule: let the agent do the reading and the drafting, and keep the irreversible actions behind a person.
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.
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.