How to Connect Claude Code to Your CMS with MCP

Cosmic has released an MCP server that connects Claude Code to its CMS, exposing 18 tools for reading and writing content directly from the AI assistant. Developers can set up the integration in about five minutes using a hosted endpoint or a local npm package, with read-only access recommended before enabling write capabilities.

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.