Connect Cosmic to Cursor / Claude Code with MCP

Your AI coding tools are already capable of reading and writing files, running terminal commands, and reasoning about your codebase. With an MCP (Model Context Protocol) server, you can extend that same access to your CMS content, so Cursor or Claude Code can query your Cosmic bucket, create new content objects, and update existing ones without you ever leaving the editor.

This lesson covers everything from what MCP is, to having a working Cosmic MCP server running locally in under 15 minutes.

---

What Is MCP?

MCP (Model Context Protocol) is an open standard that lets AI tools like Cursor and Claude Code connect to external data sources and APIs through a standardized interface. When you add an MCP server to your editor, the AI gains a set of typed tools it can call in response to your natural-language prompts.

Instead of copying and pasting content IDs into your code or leaving the editor to check what fields a content type has, you can ask your AI directly:

"Fetch the three most recent blog posts from my Cosmic bucket and show me their titles and slugs."

The AI calls the MCP server, the server talks to Cosmic's REST API, and the result comes back in your editor context.

---

What This Removes

Headless CMS development involves a lot of context-switching: check the schema in the dashboard, copy the object type slug, paste it into your code, check the API response shape, update your TypeScript types. An MCP connection removes most of those trips.

With the bucket reachable from your editor you can:

• Ask the AI to scaffold a typed query for any content type

• Confirm field names and value shapes before writing fetch logic

• Create test content objects directly from a prompt during development

• Update content in staging while you are editing the page that renders it

---

Prerequisites

Before you start, you need:

• A Cosmic account and at least one bucket

• Cursor or Claude Code installed

• Node.js 18 or later

• Your Cosmic bucket slug, read key, and write key (found in your bucket under Settings > API keys)

---

Step 1: Choose Hosted or Local

Cosmic runs a hosted MCP server, so in most cases there is nothing to install. You point your editor at a URL and authenticate with your bucket keys. That is the path used in Step 2.

If you need to run the server yourself, for an offline environment or a client without remote MCP support, the same server ships as an npm package:

The package is and it requires Node.js 18 or later.

---

Step 2: Configure Your Editor

Cursor

Create in your project root and point it at the hosted server:

The bearer token accepts either on its own for read-only tools, or for full access including creating and updating content.

To run the server locally over stdio instead, use this form:

is optional. Leave it out and the write tools are still listed, but any call that tries to change something fails. Reads keep working.

This file holds live API keys, so add to your before you commit.

Claude Code

In Claude Code, run the MCP configuration command from your project root:

This registers the Cosmic MCP server in your project's Claude configuration.

---

Step 3: Verify the Connection

Restart your editor after saving the configuration. Then open the AI chat panel and try a test prompt:

"List the object types in my Cosmic bucket."

If the connection is working, the AI will call the MCP server and return a list of your content types with their slugs and field counts. If you get an error, double-check that your bucket slug and API keys are correct and that the environment variables are being passed through.

---

Step 4: Use the Cosmic SDK in Your Code

Once you know what content types and field names exist (from the MCP context), you can write clean fetch logic using the official Cosmic TypeScript SDK:

Install the SDK first if you have not already:

With MCP active, you can ask your AI to generate this kind of typed query by describing what you want in plain English. The AI already knows your field names from the MCP context, so you do not need to look them up separately.

---

What the MCP Server Exposes

The Cosmic MCP server gives your AI editor tools to:

That is a partial list. The server exposes 19 tools in total, covering objects, media, object types, AI generation, and blocks.

The AI chooses which tool to call based on your natural-language prompt. You can be specific or vague: "get me the five most recent posts" and "fetch objects of type blog-posts sorted by created_at descending limit 5" will both work.

---

Practical Prompts to Try

Once your MCP connection is live, try these prompts in your editor:

Schema discovery:

"What metafields does the blog-posts content type have? Generate TypeScript types for it."

Content creation during development:

"Create a test blog post in my Cosmic bucket with the title 'Test Post' and status draft."

Query scaffolding:

"Write a Next.js App Router page that fetches a single blog post by slug from Cosmic and renders the title and content."

Content audit:

"List all draft objects in my bucket created in the last 7 days. Show title, type, and slug."

---

Do This in Your Bucket

1. Find your bucket slug and API keys in your bucket under Settings > API keys

2. Add the Cosmic MCP server config to Cursor or Claude Code using the steps above

3. Restart your editor and open the AI chat

4. Type: "List the object types in my Cosmic bucket" and confirm you see your content types in the response

5. Follow up with: "Generate TypeScript types for my [your content type] type"

If the type generation step works, the connection is doing what it should: the model is reading your real schema rather than guessing at field names.

If it fails, the usual causes are a wrong bucket slug, keys copied with trailing whitespace, or an editor that was not restarted after the config changed.

---

Up Next

Lesson 3: Publish Content from Slack with an AI Agent

Your agent team is running and your editor is connected. In Lesson 3, you will learn how to trigger content creation directly from a Slack message, so your whole team can kick off the content pipeline without touching the dashboard.