An MCP server that gives your AI client real access to your content

The Model Context Protocol is an open standard for connecting AI clients to external systems. Cosmic ships an MCP server so the assistant you already use can read and write your actual content through a typed tool surface.

Connect your client to your bucket and it gets 18 tools: list and search objects, read a single object with its metafields, create and update content, manage media, inspect and evolve your content model, and generate text, images, video, and audio straight into your media library.

Everything runs against the same REST API and JavaScript SDK your application already uses, so anything the agent writes is immediately available to your front end.

There are two scopes. /v1/buckets/{your-bucket-slug} serves a human who already has a bucket, and exposes the 18 bucket-scoped tools. /v1/agent serves a human who has no Cosmic account yet, and lets an agent provision one for them. The full reference for both lives in the MCP server docs.

If you want a walkthrough rather than a reference, we have step-by-step guides for connecting Claude Desktop to Cosmic and for connecting Claude Code to Cosmic. For help writing application code against the SDK, see Agent Skills, which is the companion surface to this one.

Hosted (recommended)

Add one entry to your MCP config in Claude Desktop or Cursor:

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

Drop the :your-write-key suffix for read-only access.

Claude Desktop reads ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows. Cursor reads .cursor/mcp.json in your project, or ~/.cursor/mcp.json globally.

Self-hosted over stdio

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

Your bucket slug, read key, and write key live in the Cosmic dashboard under Settings, then API Access. Once connected, you can ask in plain language: list all blog posts in my Cosmic bucket, show me every image in the blog-images folder, or create a new object type called Products with name, price, description, and image fields.

The package is open source on GitHub and published on npm.

No Cosmic account yet? Use the agent scope

If the person you are helping has never used Cosmic, point your client at the agent endpoint instead:

{
  "mcpServers": {
    "cosmic-agent-signup": {
      "url": "https://mcp.cosmicjs.com/v1/agent"
    }
  }
}

cosmic_agent_signup is unauthenticated and takes a human_email, a project_name, and your agent_id. It returns an agent_key, a read key, a write key, and a claim URL, and Cosmic emails the human a 6-digit code. cosmic_agent_verify submits that code and lifts restricted-mode limits. cosmic_agent_status checks claim status and recovers the keys. Once verified, the agent switches to the bucket scope using the keys it already holds, and starts creating content in the same conversation.

New buckets start in restricted mode: no AI credits, a maximum of 50 objects, and 5 MB of media. Unclaimed projects are hard-deleted after 14 days. The agent scope docs cover the full lifecycle, error codes, and limits.