MCP Server

MCP (Model Context Protocol) server that exposes Cosmic CMS functionality as tools for AI assistants. Manage your content, media, object types, and generate AI content directly through Claude, Cursor, or any MCP-compatible client.

You can connect in two ways:

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

Hosted MCP

The hosted endpoint is the fastest way to connect Cosmic to an AI assistant. It supports the streamable-HTTP MCP transport and is ready to use today:

https://mcp.cosmicjs.com/v1/buckets/{your-bucket-slug}

Authentication

Cosmic uses separate read and write keys per bucket. Combine them in the Authorization: Bearer header:

The write key is the part after the colon. Omit it (and the colon) for read-only access. Examples:

# Read-only access
Authorization: Bearer rk_abc123def456

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

If your client can't include a colon-packed token, you can send the write key out-of-band via the X-Cosmic-Write-Key header instead.

Getting your credentials

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

Claude Desktop (hosted)

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "cosmic": {
      "url": "https://mcp.cosmicjs.com/v1/buckets/your-bucket-slug",
      "headers": {
        "Authorization": "Bearer your-read-key:your-write-key"
      }
    }
  }
}

Cursor (hosted)

Add the following to your Cursor MCP settings (.cursor/mcp.json in your project or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "cosmic": {
      "url": "https://mcp.cosmicjs.com/v1/buckets/your-bucket-slug",
      "headers": {
        "Authorization": "Bearer your-read-key:your-write-key"
      }
    }
  }
}

For read-only access, drop the :your-write-key suffix from the bearer token. Write tools (*_create, *_update, *_delete, AI generation) will be blocked with a clear error message; read tools work as normal.

Self-hosted (stdio)

Prefer to run the MCP locally? The @cosmicjs/mcp npm package ships a stdio-based binary you can launch via npx.

Installation

npx @cosmicjs/mcp

Or install globally:

npm install -g @cosmicjs/mcp

Configuration

The stdio binary reads its credentials from environment variables:

Claude Desktop (self-hosted)

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

Cursor (self-hosted)

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

Available Tools

The MCP server provides 18 tools for managing your Cosmic content:

Objects

Media

Object Types

AI Generation

Usage Examples

Once configured, you can interact with your Cosmic bucket using natural language:

Content Management

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

Media

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

Upload this image URL to my media library: https://example.com/image.jpg

Schema Management

Show me all object types in my bucket

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

AI Generation

Generate a product description for a wireless bluetooth headphone

Generate an image of a futuristic city skyline at sunset 
and upload it to my media library

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

MCP Server vs Agent Skills

The MCP server and Agent Skills serve different but complementary purposes:

Use both together for the best experience:

• Agent Skills helps your AI write application code that uses the Cosmic SDK
• MCP Server lets your AI directly manage content in your bucket

Resources

• Cosmic Documentation
• API Reference
• Agent Skills
• Discord Community