# 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.

**New: hosted MCP available now.** Connect any MCP client to `https://mcp.cosmicjs.com/v1/buckets/{your-bucket-slug}` with your bucket keys, no install required. Jump to the [Hosted MCP](#hosted-mcp) section to get started.

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:

| Access level | Authorization header |
|---|---|
| Read-only tools | `Authorization: Bearer READ_KEY` |
| Full access (read + write) | `Authorization: Bearer READ_KEY:WRITE_KEY` |

The write key is the part after the colon. Omit it (and the colon) for read-only access. Examples:
```text
# 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](https://app.cosmicjs.com)
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`
```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):
```json
{
  "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
```bash
npx @cosmicjs/mcp

```
Or install globally:
```bash
npm install -g @cosmicjs/mcp

```
### Configuration

The stdio binary reads its credentials from environment variables:

| Variable | Required | Description |
|----------|----------|-------------|
| `COSMIC_BUCKET_SLUG` | Yes | Your Cosmic bucket slug |
| `COSMIC_READ_KEY` | Yes | Bucket read key for read operations |
| `COSMIC_WRITE_KEY` | No | Bucket write key for write operations |

### Claude Desktop (self-hosted)
```json
{
  "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)
```json
{
  "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

| Tool | Description |
|------|-------------|
| `cosmic_objects_list` | List or search content objects, filtered by type, status, locale, and paginated. **Use when** the agent needs to enumerate existing content, find an object by title, or build a list view. |
| `cosmic_objects_get` | Fetch a single content object by ID or slug, with optional metafield, depth, and locale params. **Use when** the agent already knows which object to operate on and needs its full body. |
| `cosmic_objects_create` | Create a new content object of a given type with title, slug, status, and metafields (requires write key). **Use when** the human asks to add a blog post, product, page, or any other piece of content. |
| `cosmic_objects_update` | Update an existing object's title, slug, status, or metafield values (requires write key). **Use when** editing copy, publishing a draft, or changing structured data on an existing object. |
| `cosmic_objects_delete` | Permanently delete a content object by ID (requires write key). **Use when** the human explicitly asks to remove content; never call speculatively. |

### Media

| Tool | Description |
|------|-------------|
| `cosmic_media_list` | List media files in the bucket, optionally scoped to a folder. **Use when** the agent needs to find an existing image, video, or document before referencing it in content. |
| `cosmic_media_get` | Fetch metadata and the imgix URL for a single media file by ID. **Use when** the agent needs the canonical URL or dimensions for a known asset. |
| `cosmic_media_upload` | Upload a media file from a URL or base64 payload into the bucket's media library (requires write key). **Use when** the human supplies an image/file or an asset needs to be moved from an external source into Cosmic. |
| `cosmic_media_delete` | Delete a media file from the bucket (requires write key). **Use when** the human explicitly asks to remove an asset. |

### Object Types

| Tool | Description |
|------|-------------|
| `cosmic_types_list` | List every object type (content model) in the bucket. **Use when** the agent first connects to a bucket and needs to learn the available content shapes before reading or writing. |
| `cosmic_types_get` | Fetch the full schema (metafields, options, helper text) for one object type by slug. **Use when** the agent needs the exact metafield keys and types before creating or updating an object. |
| `cosmic_types_create` | Create a new object type with a metafield schema (requires write key). **Use when** the human asks to model a new kind of content (e.g. "add a Products section"). |
| `cosmic_types_update` | Update an object type's schema or metafield definitions (requires write key). **Use when** evolving an existing content model: adding a field, changing options, or renaming. |
| `cosmic_types_delete` | Delete an object type and all its objects (requires write key). **Use when** the human explicitly asks to drop a content model; destructive, prompt for confirmation. |

### AI Generation

| Tool | Description |
|------|-------------|
| `cosmic_ai_generate_text` | Generate text content using Cosmic AI with optional context from existing objects. **Use when** the human asks to draft, rewrite, summarize, or translate copy and wants the bucket's own content as context. |
| `cosmic_ai_generate_image` | Generate an AI image and store it in the bucket's media library (requires write key). **Use when** the human needs original imagery that should live in Cosmic rather than an external host. |
| `cosmic_ai_generate_video` | Generate an AI video with Google Veo and store it in the media library (requires write key). **Use when** the human asks for short generated video clips tied to a piece of content. |
| `cosmic_ai_generate_audio` | Generate narration audio from text via OpenAI TTS (13 voices) and store it in the media library (requires write key). **Use when** the human asks for voiceover, podcast intros, or accessibility audio for written content. |

The hosted endpoint exposes one more scope, `/v1/agent`, with three tools dedicated to the [agent signup flow](#agent-scope). 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](/docs/agent-skills#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](/docs/api/agents).

| Tool | Auth | Description |
|---|---|---|
| `cosmic_agent_signup` | None | Create an unclaimed project + 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` | `agent_key` | Submit the 6-digit OTP. Lifts restricted-mode limits and enables AI generation on the bucket. |
| `cosmic_agent_status` | `agent_key` | Check claim status, remaining limits, and recover the bucket keys. |

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](/docs/api/agents) 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).

```bash
# 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)

```json
{
  "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)

```json
{
  "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.

| Variable | Required | Description |
|---|---|---|
| `COSMIC_MCP_SCOPE` | Yes | Set to `agent` to load the agent tools instead of the bucket tools. |
| `COSMIC_AGENT_KEY` | No | If set, the `verify` and `status` tools authenticate with this key. If unset, only `cosmic_agent_signup` works until you run it once and capture the returned key. |
| `COSMIC_DAPI_URL` | No | Override the dashboard API base URL. Defaults to `https://dapi.cosmicjs.com/v3`. |

```json
{
  "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:

| Feature | MCP Server | Agent Skills |
|---------|------------|--------------|
| **Purpose** | Direct content management | Code generation guidance |
| **Use case** | "List my blog posts" | "Build a blog with Cosmic" |
| **How it works** | AI calls tools to interact with your bucket | AI writes code using the SDK |
| **Best for** | Managing content while developing | Building applications |

**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](/docs)
- [API Reference](/docs/api)
- [Agent Skills](/docs/agent-skills)
- [Discord Community](https://discord.com/invite/MSCwQ7D6Mg)