{"slug": "how-to-connect-claude-code-to-your-cms-with-mcp", "title": "How to Connect Claude Code to Your CMS with MCP", "summary": "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.", "body_md": "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.\n\nThis guide connects Claude Code to a Cosmic bucket. With the hosted endpoint it takes about five minutes and requires no install.\n\nMCP is an open protocol for exposing tools to AI assistants. The Cosmic MCP server implements it and exposes **18 tools** across four areas:\n\nOnce 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.\n\nThere are two ways to connect:\n\n`https://mcp.cosmicjs.com/v1/buckets/{your-bucket-slug}`\n\nand authenticate with your bucket keys. Nothing to install.`@cosmicjs/mcp`\n\nnpm package locally via `npx`\n\n. Useful for offline work, or when you want the MCP process running inside your own dev environment.You need three things:\n\nThe 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`\n\n.\n\nA 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.\n\nClaude Code picks up project-scoped MCP servers from a `.mcp.json`\n\nfile at the root of your repository. Create it with:\n\n```\n{\n  \"mcpServers\": {\n    \"cosmic\": {\n      \"url\": \"https://mcp.cosmicjs.com/v1/buckets/your-bucket-slug\",\n      \"headers\": {\n        \"Authorization\": \"Bearer your-read-key:your-write-key\"\n      }\n    }\n  }\n}\n```\n\nReplace `your-bucket-slug`\n\n, `your-read-key`\n\n, and `your-write-key`\n\nwith the values from Step 1. The endpoint supports the streamable-HTTP MCP transport.\n\nCosmic packs both keys into a single bearer token, separated by a colon. The write key is the part after the colon:\n\n```\n# Read-only access\nAuthorization: Bearer rk_abc123def456\n\n# Full access (read + write)\nAuthorization: Bearer rk_abc123def456:wk_zyx987wvu654\n```\n\nOmit 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`\n\nheader instead.\n\nOne housekeeping note: `.mcp.json`\n\nnow contains live credentials, so add it to `.gitignore`\n\nbefore your next commit.\n\nThe same `mcpServers`\n\nblock 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`\n\non macOS and `.cursor/mcp.json`\n\nfor Cursor.\n\nIf you would rather run the server yourself, the `@cosmicjs/mcp`\n\npackage ships a stdio binary. Point Claude Code at `npx`\n\n:\n\n```\n{\n  \"mcpServers\": {\n    \"cosmic\": {\n      \"command\": \"npx\",\n      \"args\": [\"@cosmicjs/mcp\"],\n      \"env\": {\n        \"COSMIC_BUCKET_SLUG\": \"your-bucket-slug\",\n        \"COSMIC_READ_KEY\": \"your-read-key\",\n        \"COSMIC_WRITE_KEY\": \"your-write-key\"\n      }\n    }\n  }\n}\n```\n\nThe stdio binary reads credentials from environment variables:\n\n`COSMIC_BUCKET_SLUG`\n\n(required): your Cosmic bucket slug`COSMIC_READ_KEY`\n\n(required): bucket read key for read operations`COSMIC_WRITE_KEY`\n\n(optional): bucket write key for write operationsLeave `COSMIC_WRITE_KEY`\n\nout entirely for a read-only server. You can also install it globally with `npm install -g @cosmicjs/mcp`\n\ninstead of resolving it through `npx`\n\neach time.\n\nRestart Claude Code and run:\n\n```\n/mcp\n```\n\nYou should see `cosmic`\n\nlisted with its tools. Then confirm it can actually reach your bucket by asking for something only your bucket knows:\n\n```\nList all object types in my Cosmic bucket\n```\n\nClaude Code should call `cosmic_types_list`\n\nand return your real content models. If it returns your object types, the connection is live and correctly authenticated.\n\n`cosmic_objects_list`\n\n: list or search objects, filtered by type, status, and locale, with pagination`cosmic_objects_get`\n\n: fetch a single object by ID or slug, with optional metafield, depth, and locale params`cosmic_objects_create`\n\n: create a new object with title, slug, status, and metafields (write key required)`cosmic_objects_update`\n\n: update an existing object's title, slug, status, or metafield values (write key required)`cosmic_objects_delete`\n\n: permanently delete an object by ID (write key required)`cosmic_media_list`\n\n: list media files, optionally scoped to a folder`cosmic_media_get`\n\n: fetch metadata and the imgix URL for a single file`cosmic_media_upload`\n\n: upload from a URL or base64 payload into the media library (write key required)`cosmic_media_delete`\n\n: delete a media file (write key required)`cosmic_types_list`\n\n: list every object type in the bucket`cosmic_types_get`\n\n: fetch the full schema for one object type, including metafields, options, and helper text`cosmic_types_create`\n\n: create a new object type with a metafield schema (write key required)`cosmic_types_update`\n\n: update a type's schema or metafield definitions (write key required)`cosmic_types_delete`\n\n: delete an object type and all its objects (write key required)`cosmic_ai_generate_text`\n\n: generate text with optional context pulled from existing objects in your bucket`cosmic_ai_generate_image`\n\n: generate an image and store it in the media library (write key required)`cosmic_ai_generate_video`\n\n: generate video with Google Veo and store it in the media library (write key required)`cosmic_ai_generate_audio`\n\n: 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`\n\nand `cosmic_types_get`\n\n. An agent that reads your schema before writing produces valid metafields on the first attempt instead of guessing key names and failing.\n\nThis is the part to get right before you point an agent at a production bucket.\n\nWith 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`\n\n, `*_update`\n\n, and `*_delete`\n\ntool, plus all four AI generation tools, since each of those writes generated assets into your media library.\n\nSo 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.\n\nWith the server connected, these are all single prompts:\n\n```\nList all blog posts in my Cosmic bucket\nCreate a new blog post titled \"Getting Started with MCP\" with the content\n\"This is an introduction to the Model Context Protocol...\"\nUpdate the blog post with ID \"abc123\" to change its status to published\nShow me all images in the \"blog-images\" folder\nCreate a new object type called \"Products\" with fields for name, price,\ndescription, and image\nGenerate audio narration of \"Welcome to Cosmic CMS\" using the \"nova\" voice\nand upload it to my media library\n```\n\nThe 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.\n\nThe hosted endpoint exposes a second, smaller scope at `https://mcp.cosmicjs.com/v1/agent`\n\nfor 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:\n\n`cosmic_agent_signup`\n\n(no auth): creates an unclaimed project and bucket tied to a `human_email`\n\n. Returns the `agent_key`\n\n, `read_key`\n\n, `write_key`\n\n, and a `claim_url`\n\n. Cosmic emails the human a 6-digit OTP.`cosmic_agent_verify`\n\n(requires `agent_key`\n\n): submits the OTP, lifts restricted-mode limits, and enables AI generation.`cosmic_agent_status`\n\n(requires `agent_key`\n\n): 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.\n\nThe 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.\n\nCosmic offers two things that sound similar and do different jobs:\n\nUse both. Agent Skills helps Claude Code write code like this:\n\n``` js\nimport { createBucketClient } from '@cosmicjs/sdk';\n\nconst cosmic = createBucketClient({\n  bucketSlug: 'your-bucket-slug',\n  readKey: 'your-read-key',\n});\n\nconst { objects: posts } = await cosmic.objects\n  .find({ type: 'blog-posts' })\n  .props(['title', 'slug', 'metadata'])\n  .depth(1);\n```\n\nThe 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.\n\nFour habits worth adopting:\n\n`cosmic_objects_delete`\n\n, `cosmic_media_delete`\n\n, and especially `cosmic_types_delete`\n\nare 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\n\n`.mcp.json`\n\nis 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\"`\n\nalongside `url`\n\n.** npx cannot find the package.** The package name is\n\n`@cosmicjs/mcp`\n\n, scoped, including the `@`\n\n. 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`\n\nwith a colon and no spaces, or send the write key via `X-Cosmic-Write-Key`\n\n.\n\n**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.\n\n**Tools connect but return nothing.** Confirm you are pointed at the bucket you think you are. Ask Claude Code to run `cosmic_types_list`\n\nand compare the result against the dashboard.\n\nStart 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).\n\n**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).\n\n*Originally published on the Cosmic blog.*", "url": "https://wpnews.pro/news/how-to-connect-claude-code-to-your-cms-with-mcp", "canonical_source": "https://dev.to/tonyspiro/how-to-connect-claude-code-to-your-cms-with-mcp-3n95", "published_at": "2026-07-30 22:08:46+00:00", "updated_at": "2026-07-30 22:31:24.986956+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "large-language-models"], "entities": ["Cosmic", "Claude Code", "Model Context Protocol", "Anthropic"], "alternates": {"html": "https://wpnews.pro/news/how-to-connect-claude-code-to-your-cms-with-mcp", "markdown": "https://wpnews.pro/news/how-to-connect-claude-code-to-your-cms-with-mcp.md", "text": "https://wpnews.pro/news/how-to-connect-claude-code-to-your-cms-with-mcp.txt", "jsonld": "https://wpnews.pro/news/how-to-connect-claude-code-to-your-cms-with-mcp.jsonld"}}