How to Connect Claude Code to Your CMS with MCP

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.

What MCP actually gives Claude Code

MCP is an open protocol for exposing tools to AI assistants. The Cosmic MCP server implements it and exposes 18 tools across four areas:

• Objects (5 tools): list, get, create, update, and delete content
• Media (4 tools): list, get, upload, and delete files
• Object Types (5 tools): list, get, create, update, and delete content models
• AI Generation (4 tools): generate text, images, video, and audio into your bucket

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:

• Hosted MCP (recommended): point your client at https://mcp.cosmicjs.com/v1/buckets/{your-bucket-slug} and authenticate with your bucket keys. Nothing to install.
• Self-hosted (stdio): run the @cosmicjs/mcp npm package locally via npx. Useful for offline work, or when you want the MCP process running inside your own dev environment.

Before you start

You need three things:

1. A Cosmic bucket. The Free plan is $0/month and includes 1 Bucket, 2 team members, and 1,000 Objects, which is more than enough to follow along. Start for free.
2. Your bucket slug, read key, and write key. Step 1 below covers where to find them.
3. Claude Code installed.

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.

Step 1: Get your bucket credentials

1. Log in to the Cosmic dashboard
2. Navigate to your bucket
3. Go to Settings -> API Access
4. Copy your bucket slug, read key, and write key

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.

Step 2: Connect with hosted MCP (recommended)

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"
      }
    }
  }
}

Enter fullscreen mode Exit fullscreen mode

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.

How the authorization header works

Cosmic packs both keys into a single bearer token, separated by a colon. The write key is the part after the colon:

# Read-only access
Authorization: Bearer rk_abc123def456

# Full access (read + write)
Authorization: Bearer rk_abc123def456:wk_zyx987wvu654

Enter fullscreen mode Exit fullscreen mode

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.

Step 2, alternative: self-hosted over stdio

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"
      }
    }
  }
}

Enter fullscreen mode Exit fullscreen mode

The stdio binary reads credentials from environment variables:

• COSMIC_BUCKET_SLUG (required): your Cosmic bucket slug
• COSMIC_READ_KEY (required): bucket read key for read operations
• COSMIC_WRITE_KEY (optional): bucket write key for write operations

Leave 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.

Step 3: Verify the connection

Restart Claude Code and run:

/mcp

Enter fullscreen mode Exit fullscreen mode

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

Enter fullscreen mode Exit fullscreen mode

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.

The 18 tools, and when each one fires

Objects

• cosmic_objects_list: list or search objects, filtered by type, status, and locale, with pagination
• cosmic_objects_get: fetch a single object by ID or slug, with optional metafield, depth, and locale params
• cosmic_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)

Media

• cosmic_media_list: list media files, optionally scoped to a folder
• cosmic_media_get: fetch metadata and the imgix URL for a single file
• cosmic_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)

Object Types

• cosmic_types_list: list every object type in the bucket
• cosmic_types_get: fetch the full schema for one object type, including metafields, options, and helper text
• cosmic_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)

AI Generation

• cosmic_ai_generate_text: generate text with optional context pulled from existing objects in your bucket
• cosmic_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.

Read-only vs full access

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.

What this looks like in practice

With the server connected, these are all single prompts:

List all blog posts in my Cosmic bucket

Enter fullscreen mode Exit fullscreen mode

Create a new blog post titled "Getting Started with MCP" with the content
"This is an introduction to the Model Context Protocol..."

Enter fullscreen mode Exit fullscreen mode

Update the blog post with ID "abc123" to change its status to published

Enter fullscreen mode Exit fullscreen mode

Show me all images in the "blog-images" folder

Enter fullscreen mode Exit fullscreen mode

Create a new object type called "Products" with fields for name, price,
description, and image

Enter fullscreen mode Exit fullscreen mode

Generate audio narration of "Welcome to Cosmic CMS" using the "nova" voice
and upload it to my media library

Enter fullscreen mode Exit fullscreen mode

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.

Agent scope: when the human has no Cosmic account yet

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.

MCP server vs Agent Skills

Cosmic offers two things that sound similar and do different jobs:

• MCP server is for direct content management. It answers “list my blog posts.” The AI calls tools that operate on your bucket.
• Agent Skills is for code generation guidance. It answers “build a blog with Cosmic.” The AI writes application code using the SDK.

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);

Enter fullscreen mode Exit fullscreen mode

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.

Guardrails for production buckets

Four habits worth adopting:

1. Read key first. Connect with a read-only token for your first few sessions. Add the write key when you have seen what the agent actually does.
2. Experiment in a separate bucket. Bucket allowances scale with your plan: Free includes 1, Builder ($49/month) includes 2, Team ($299/month) includes 3, and Business ($499/month) includes 5. Point destructive experiments at a bucket you do not mind losing.
3. Treat the delete tools as manual-approval only. 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.
4. Mind your seats. Plans include a set number of team members (Free 2, Builder 3, Team 5, Business 10) and additional users are $29/user/month, so decide who needs dashboard access rather than adding everyone by default.

Troubleshooting

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.

Next steps

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.