5 分钟将 Claude 接入 CMS：Cosmic MCP Server 实战指南

What MCP actually gives you

Model Context Protocol 是 AI 客户端发现和调用工具的标准方式。不需要你用文字向 Claude 描述你的 CMS，Claude 直接向服务器查询有哪些工具可用，然后调用它们。

Cosmic 的 MCP 服务器暴露了 18 个基于 Bucket 作用域的工具，涵盖对象、对象类型、媒体和 AI 生成。"基于 Bucket 作用域"是关键：服务器操作的是单个 Bucket，使用你提供的密钥，无法访问你其他的 Buckets。

The five-minute setup

1. Get your Bucket keys

在你的 Cosmic 仪表盘中，打开你的 Bucket，然后进入 Settings > API Access。复制三样东西：Bucket slug、read key 和 write key。密钥是故意分开的，这种分离是整个设置中最有用的控制手段。详见下文。

2. Add the server to your MCP client config

托管端点是最快的路径，无需安装。将客户端指向 https://mcp.cosmicjs.com/v1/buckets/{your-bucket-slug}，并在 Authorization header 中用密钥认证。

对于 Claude Desktop，编辑配置文件：

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 在 .cursor/mcp.json 中使用相同结构，可以是单项目配置，也可以是全局配置 ~/.cursor/mcp.json。

仔细检查 bearer token 的格式：read key、冒号、write key。去掉 :your-write-key 后缀，连接就变成只读了。记住这个细节，因为在将任何配置指向生产环境之前，这是值得理解的核心控制点。

如果你更希望在本地开发环境中运行 MCP 进程，@cosmicjs/mcp 包提供了一个 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"
      }
    }
  }
}

保存文件并重启客户端。Cosmic 工具会出现在工具列表中。

3. Verify the connection

先用只读操作验证连接：

"List the object types in this Bucket and tell me how many objects are in each."

如果返回的是你真实的内容模型，说明已连接成功。如果没有返回任何内容，说明 key 或 Bucket slug 有误，错误信息会指明是哪个。

一旦读取正常工作，有用的 prompt 示例如下：

"Find every published blog post missing an SEO description and list the slugs."

"Create a draft post from this outline, set the author to Tony Spiro, and leave status as draft."

"Add alt text to every image in the media library that does not have any."

最后一个是那种永远不会手动完成的琐碎任务，但交给 Agent 大约一分钟就能搞定。

The control that matters: read keys and write keys

在向 Agent 开放你的生产 Bucket 之前，这里是值得理解的部分。

Cosmic 会生成独立的 read key 和 write key。给 MCP 客户端提供一个只读密钥，它只能获得读取工具。每个写入工具都会返回明确的 blocked 错误。不会猜测，不会从 system prompt 推断，再多的巧妙 prompt 也无法绕过。

你可以在不到一分钟内自己验证这一点：

将 Authorization header 设置为 Bearer your-read-key（不附带 write key 和冒号）

让 Claude 创建一个新对象

阅读它返回的 blocked 错误

这是一个可验证的护栏，而不是一份政策文档。对于将 Agent 连接到真实内容的人，这也是诚实的初始姿态：先只读，然后在对工作流建立信任后谨慎地扩大范围。

当你准备启用写入时，安全模式是将一个启用了写入的密钥指向一个 staging Bucket，而生产 Bucket 保持只读。Cosmic 的套餐从 Builder 起就包含多个 Bucket，因此为 Agent 工作设置一个专用的 staging Bucket 是合理的配置，而非特殊安排。

Writing content through the API instead

如果你更希望通过脚本而不是聊天来驱动工作流，TypeScript SDK 覆盖了同样的功能：

npm install @cosmicjs/sdk

import { createBucketClient } from '@cosmicjs/sdk';

const cosmic = createBucketClient({
  bucketSlug: process.env.COSMIC_BUCKET_SLUG!,
  readKey: process.env.COSMIC_READ_KEY!,
  writeKey: process.env.COSMIC_WRITE_KEY!,
});

// Read: find drafts with no SEO description
const { objects: posts } = await cosmic.objects
  .find({ type: 'blog-posts', status: 'draft' })
  .props('id,title,slug,metadata.seo_description');

const missing = posts.filter((p) => !p.metadata?.seo_description);

// Write: patch one of them
await cosmic.objects.updateOne(missing[0].id, {
  metadata: {
    seo_description: 'A short, specific summary under 155 characters.',
  },
});

注意 writeKey 是独立于 readKey 的参数。省掉它，所有写入调用都会失败，这与 MCP 服务器依赖的护栏机制相同。

What this is good for, and what it is not

适用的场景：

• 内容审计：缺失的元数据、损坏的内部链接、过时的日期、孤立的对象
• 批量机械编辑：alt 文本、SEO 描述、标签规范化、分类清理
• 基于真实内容模型生成草稿，确保第一次生成的形状就是正确的
• 回答关于你自己的内容库的问题，而无需打开仪表盘

不适用的场景：

• 无人监管地向生产环境发布内容。保留人工审核发布步骤。
• 任何错误写入代价高昂且难以撤销的操作。

实际规则：让 Agent 做读取和起草的工作，把不可逆的操作留给人。

Frequently asked questions

Do I need a paid plan to use the MCP server? 你可以在免费计划上开始，包含 1 个 Bucket、2 名团队成员和 1,000 个 Objects。如果你想为 Agent 写入设置一个独立的 staging Bucket，则需要 Builder 计划（$49/月，2 个 Buckets、3 名团队成员、5,000 个 Objects）。

Does Cosmic offer a GraphQL endpoint for this? 没有。Cosmic 提供 REST API 和 JavaScript/TypeScript SDK。MCP 服务器基于同一个 REST API 构建。

Can I limit which object types an agent can touch? 密钥级别的控制是 read 与 write。若要更细粒度的作用域控制，可以让 Agent 只访问只包含你希望它操作的内容的 Bucket。

Does this work with clients other than Claude? MCP 是一个客户端无关的标准，任何兼容 MCP 的客户端都可以用相同的 18 个工具连接到同一个服务器。上面已经介绍了 Cursor，托管端点使用 streamable-HTTP 传输，其他客户端也可以使用。

Try it on a real Bucket

理解 Agent 在有真实内容模型支撑下能做什么，最快的方法是连接一个然后向它提问你自己的内容。

创建一个免费的 Cosmic 账户，无需信用卡。

阅读 MCP 服务器文档获取精确的客户端配置。

Want a walkthrough of the agent workflows other teams are running? Book 30 minutes with Tony

Cosmic 是 YC W19 公司，为希望让自己的 AI 工具对接真实、结构化内容的团队构建内容层，而不是把内容复制粘贴到聊天框里。