# How to Connect Claude Code to Your CMS with MCP

> Source: <https://dev.to/tonyspiro/how-to-connect-claude-code-to-your-cms-with-mcp-3n95>
> Published: 2026-07-30 22:08:46+00:00

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:

```
# Read-only access
Authorization: Bearer rk_abc123def456

# Full access (read + write)
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](https://www.cosmicjs.com/docs/mcp-server?utm_source=devto&utm_medium=referral&utm_campaign=connect-claude-code-to-cms-with-mcp) 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 slug`COSMIC_READ_KEY`

(required): bucket read key for read operations`COSMIC_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 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)`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)`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)`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.

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:

``` js
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](https://www.cosmicjs.com/docs/mcp-server?utm_source=devto&utm_medium=referral&utm_campaign=connect-claude-code-to-cms-with-mcp).

**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](https://app.cosmicjs.com/signup?utm_source=devto&utm_medium=referral&utm_campaign=connect-claude-code-to-cms-with-mcp) and connect Claude Code in about five minutes. Evaluating Cosmic for a team? [Book a call with Tony](https://calendly.com/tonyspiro/cosmic-intro).

*Originally published on the Cosmic blog.*