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

The hosted endpoint exposes one more scope, /v1/agent, with three tools dedicated to the agent signup flow. The bucket-scoped tools above are not available on the agent endpoint and vice-versa.

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

Agent scope

The agent scope is a second, smaller MCP server dedicated to the Agent Signup flow: an AI agent can provision a brand new Cosmic project + bucket for a human who does not yet have a Cosmic account, without leaving the MCP transport. It exposes three tools that proxy to the Agents REST API.

The bucket starts in restricted mode (no AI credits, max 50 objects, max 5 MB media). Unclaimed projects are hard-deleted after 14 days. See the REST API reference for the full lifecycle, error codes, and limits.

Hosted endpoint

https://mcp.cosmicjs.com/v1/agent

cosmic_agent_signup is unauthenticated; cosmic_agent_verify and cosmic_agent_status require Authorization: Bearer agk_... (the agent_key returned from sign-up).

# Discover the tools
curl -X POST https://mcp.cosmicjs.com/v1/agent \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Sign up (no auth)
curl -X POST https://mcp.cosmicjs.com/v1/agent \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "cosmic_agent_signup",
      "arguments": {
        "human_email": "tony@example.com",
        "project_name": "Recipe Blog",
        "agent_id": "my-agent-platform"
      }
    }
  }'

# Verify with the agent_key from sign-up
curl -X POST https://mcp.cosmicjs.com/v1/agent \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer agk_..." \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "cosmic_agent_verify",
      "arguments": { "code": "123456" }
    }
  }'

Claude Desktop (agent scope)

{
  "mcpServers": {
    "cosmic-agent-signup": {
      "url": "https://mcp.cosmicjs.com/v1/agent"
    },
    "cosmic-agent-session": {
      "url": "https://mcp.cosmicjs.com/v1/agent",
      "headers": {
        "Authorization": "Bearer agk_your-agent-key"
      }
    }
  }
}

Two entries are useful in practice: an unauthenticated one for the initial sign-up call, and a second authenticated entry once the agent has captured the returned agent_key. The agent can omit the second entry until needed.

Cursor (agent scope)

{
  "mcpServers": {
    "cosmic-agent": {
      "url": "https://mcp.cosmicjs.com/v1/agent",
      "headers": {
        "Authorization": "Bearer agk_your-agent-key"
      }
    }
  }
}

Self-hosted (stdio)

Set COSMIC_MCP_SCOPE=agent to expose only the signup tools from the stdio binary. Useful for desktop agents that want the MCP process inside their dev environment.

{
  "mcpServers": {
    "cosmic-agent": {
      "command": "npx",
      "args": ["@cosmicjs/mcp"],
      "env": {
        "COSMIC_MCP_SCOPE": "agent",
        "COSMIC_AGENT_KEY": "agk_your-agent-key"
      }
    }
  }
}

When to use which scope

• /v1/buckets/{slug} - the human already has a bucket. The agent reads, writes, and generates content with the bucket keys.
• /v1/agent - the human has no Cosmic account yet. The agent provisions a project on their behalf, hands them an OTP, and graduates to the bucket scope (or any other bucket-scoped surface) once verified.

It's common for a single conversation to use both: the agent calls cosmic_agent_signup, captures the bucket keys, and switches to the bucket-scoped tools to start creating content.

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