Claude Code is fluent in your repository and blind to your content. It can refactor the component that renders your blog, but ask it to publish the post that component displays and it has nowhere to look. The Model Context Protocol (MCP) closes that gap. It gives Claude Code a set of tools it can call against your CMS directly, so reading and writing content happens in the same conversation as the code.
This guide connects Claude Code to a Cosmic bucket. With the hosted endpoint it takes about five minutes and requires no install.
MCP is an open protocol for exposing tools to AI assistants. The Cosmic MCP server implements it and exposes 18 tools across four areas:
Once connected, "publish the MCP draft and generate a hero image for it" resolves to real tool calls against your bucket. No browser tab, no copy-paste, no manual export.
There are two ways to connect:
https://mcp.cosmicjs.com/v1/buckets/{your-bucket-slug}
and authenticate with your bucket keys. Nothing to install.@cosmicjs/mcp
npm package locally via npx
. Useful for offline work, or when you want the MCP process running inside your own dev environment.You need three things:
The hosted path needs no local runtime at all. Node is only required if you choose the self-hosted stdio option, since that runs through npx
.
A recommendation before you paste anything: start with the read key only. Cosmic issues separate read and write keys per bucket, so you can give Claude Code full visibility into your content while making it structurally incapable of changing it. Add the write key once you trust the setup. The read-only vs full access section below covers exactly what changes.
Claude Code picks up project-scoped MCP servers from a .mcp.json
file at the root of your repository. Create it with:
{
"mcpServers": {
"cosmic": {
"url": "https://mcp.cosmicjs.com/v1/buckets/your-bucket-slug",
"headers": {
"Authorization": "Bearer your-read-key:your-write-key"
}
}
}
}
Replace your-bucket-slug
, your-read-key
, and your-write-key
with the values from Step 1. The endpoint supports the streamable-HTTP MCP transport.
Cosmic packs both keys into a single bearer token, separated by a colon. The write key is the part after the colon:
Authorization: Bearer rk_abc123def456
Authorization: Bearer rk_abc123def456:wk_zyx987wvu654
Omit the colon and the write key for read-only access. If your client cannot send a colon-packed token, you can pass the write key out-of-band using the X-Cosmic-Write-Key
header instead.
One housekeeping note: .mcp.json
now contains live credentials, so add it to .gitignore
before your next commit.
The same mcpServers
block works for Claude Desktop and Cursor. The MCP server docs list the exact config file paths for each client, including ~/Library/Application Support/Claude/claude_desktop_config.json
on macOS and .cursor/mcp.json
for Cursor.
If you would rather run the server yourself, the @cosmicjs/mcp
package ships a stdio binary. Point Claude Code at npx
:
{
"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"
}
}
}
}
The stdio binary reads credentials from environment variables:
COSMIC_BUCKET_SLUG
(required): your Cosmic bucket slugCOSMIC_READ_KEY
(required): bucket read key for read operationsCOSMIC_WRITE_KEY
(optional): bucket write key for write operationsLeave COSMIC_WRITE_KEY
out entirely for a read-only server. You can also install it globally with npm install -g @cosmicjs/mcp
instead of resolving it through npx
each time.
Restart Claude Code and run:
/mcp
You should see cosmic
listed with its tools. Then confirm it can actually reach your bucket by asking for something only your bucket knows:
List all object types in my Cosmic bucket
Claude Code should call cosmic_types_list
and return your real content models. If it returns your object types, the connection is live and correctly authenticated.
cosmic_objects_list
: list or search objects, filtered by type, status, and locale, with paginationcosmic_objects_get
: fetch a single object by ID or slug, with optional metafield, depth, and locale paramscosmic_objects_create
: create a new object with title, slug, status, and metafields (write key required)cosmic_objects_update
: update an existing object's title, slug, status, or metafield values (write key required)cosmic_objects_delete
: permanently delete an object by ID (write key required)cosmic_media_list
: list media files, optionally scoped to a foldercosmic_media_get
: fetch metadata and the imgix URL for a single filecosmic_media_upload
: upload from a URL or base64 payload into the media library (write key required)cosmic_media_delete
: delete a media file (write key required)cosmic_types_list
: list every object type in the bucketcosmic_types_get
: fetch the full schema for one object type, including metafields, options, and helper textcosmic_types_create
: create a new object type with a metafield schema (write key required)cosmic_types_update
: update a type's schema or metafield definitions (write key required)cosmic_types_delete
: delete an object type and all its objects (write key required)cosmic_ai_generate_text
: generate text with optional context pulled from existing objects in your bucketcosmic_ai_generate_image
: generate an image and store it in the media library (write key required)cosmic_ai_generate_video
: generate video with Google Veo and store it in the media library (write key required)cosmic_ai_generate_audio
: generate narration via OpenAI TTS, 13 voices available, stored in the media library (write key required)The two tools worth calling out for agent work are cosmic_types_list
and cosmic_types_get
. An agent that reads your schema before writing produces valid metafields on the first attempt instead of guessing key names and failing.
This is the part to get right before you point an agent at a production bucket.
With a read-only token, every write tool is blocked with a clear error message and read tools work as normal. Specifically, the blocked set is every *_create
, *_update
, and *_delete
tool, plus all four AI generation tools, since each of those writes generated assets into your media library.
So a read-only setup still lets Claude Code explore your content models, read every object, and reason about your content while it writes application code. It just cannot mutate anything. That is a good default for a first session against real data.
With the server connected, these are all single prompts:
List all blog posts in my Cosmic bucket
Create a new blog post titled "Getting Started with MCP" with the content
"This is an introduction to the Model Context Protocol..."
Update the blog post with ID "abc123" to change its status to published
Show me all images in the "blog-images" folder
Create a new object type called "Products" with fields for name, price,
description, and image
Generate audio narration of "Welcome to Cosmic CMS" using the "nova" voice
and upload it to my media library
The schema management case is the one developers tend to underestimate. Modeling content is usually a dashboard task. Through MCP it becomes something you can do from the same prompt where you are scaffolding the components that will consume it.
The hosted endpoint exposes a second, smaller scope at https://mcp.cosmicjs.com/v1/agent
for the agent signup flow. It lets an AI agent provision a brand new Cosmic project and bucket on behalf of someone who does not have an account, without leaving the MCP transport. It exposes three tools:
cosmic_agent_signup
(no auth): creates an unclaimed project and bucket tied to a human_email
. Returns the agent_key
, read_key
, write_key
, and a claim_url
. Cosmic emails the human a 6-digit OTP.cosmic_agent_verify
(requires agent_key
): submits the OTP, lifts restricted-mode limits, and enables AI generation.cosmic_agent_status
(requires agent_key
): checks claim status, remaining limits, and recovers the bucket keys.New buckets start in restricted mode: no AI credits, a maximum of 50 objects, and a 5 MB media cap. Unclaimed projects are hard-deleted after 14 days.
The bucket-scoped tools listed earlier are not available on the agent endpoint, and the agent tools are not available on the bucket endpoint. A single conversation often uses both: the agent signs the human up, captures the returned bucket keys, then switches to the bucket scope to start creating content.
Cosmic offers two things that sound similar and do different jobs:
Use both. Agent Skills helps Claude Code write code like this:
import { createBucketClient } from '@cosmicjs/sdk';
const cosmic = createBucketClient({
bucketSlug: 'your-bucket-slug',
readKey: 'your-read-key',
});
const { objects: posts } = await cosmic.objects
.find({ type: 'blog-posts' })
.props(['title', 'slug', 'metadata'])
.depth(1);
The MCP server then lets the same session manage the content that code renders. One tool writes the app, the other operates the data behind it.
Four habits worth adopting:
cosmic_objects_delete
, cosmic_media_delete
, and especially cosmic_types_delete
are permanent, and deleting an object type takes all of its objects with it. Never let an agent call these speculatively.The server does not appear in /mcp. Confirm
.mcp.json
is valid JSON at the repository root and restart Claude Code. Some Claude Code versions want the transport named explicitly, so if a hosted config still will not connect, try adding "type": "http"
alongside url
.** npx cannot find the package.** The package name is
@cosmicjs/mcp
, scoped, including the @
. Verify Node is installed and on your PATH.Write tools return an error but reads work. Your bearer token is missing the write key. Check that the header is Bearer READ_KEY:WRITE_KEY
with a colon and no spaces, or send the write key via X-Cosmic-Write-Key
.
404 from the hosted endpoint. The bucket slug in the URL is wrong. Copy it again from Settings -> API Access, since the slug is not always identical to your project's display name.
Tools connect but return nothing. Confirm you are pointed at the bucket you think you are. Ask Claude Code to run cosmic_types_list
and compare the result against the dashboard.
Start with the hosted endpoint and a read-only token. Ask Claude Code to list your object types, then ask it to summarize the content in your bucket. Once that works, add the write key and let it draft something. The full tool reference and per-client config paths live in the MCP server documentation.
Try it yourself. Cosmic is an AI-powered headless CMS with a REST API, a TypeScript SDK, and a hosted MCP server. Create a free account and connect Claude Code in about five minutes. Evaluating Cosmic for a team? Book a call with Tony.
Originally published on the Cosmic blog.