Claude Codeはリポジトリ内のコードを理解できますが、コンテンツにはアクセスできません。ブログを表示するコンポーネントをリファクタリングすることはできても、そのコンポーネントが表示する投稿を公開するよう依頼すると、参照先がありません。Model Context Protocol（MCP）がそのギャップを埋めます。Claude Codeに直接CMSに対して呼び出せるツールセットを提供し、コードと同じ会話内でコンテンツの読み書きを行えるようにします。

このガイドでは、Claude CodeをCosmicバケットに接続します。ホストされたエンドポイントを使用する場合、インストールは不要で約5分で完了します。

MCPがClaude Codeにもたらすもの

MCPはAIアシスタントにツールを公開するためのオープンプロトコルです。Cosmic MCPサーバーはこれを実装し、4つの領域にわたって18のツールを提供します：

  • オブジェクト（5ツール）：コンテンツのリスト取得、取得、作成、更新、削除
  • メディア（4ツール）：ファイルのリスト取得、取得、アップロード、削除
  • オブジェクトタイプ（5ツール）：コンテンツモデルのリスト取得、取得、作成、更新、削除
  • AI生成（4ツール）：テキスト、画像、動画、音声をバケットに生成

接続後は、「MCPドラフトを公開してヒーロー画像を生成して」という指示が、バケットに対する実際のツール呼び出しに変換されます。ブラウザタブの切り替えやコピー＆ペースト、手動エクスポートは不要です。

接続方法は2つあります：

  • ホスト型MCP（推奨）：クライアントをhttps://mcp.cosmicjs.com/v1/buckets/{your-bucket-slug}に向け、バケットキーで認証します。インストールは不要です。
  • セルフホスト（stdio）：@cosmicjs/mcp npmパッケージをnpx経由でローカル実行します。オフライン作業やMCPプロセスを独自の開発環境内で実行したい場合に便利です。

開始前の準備

以下の3つが必要です：

  1. Cosmicバケット。無料プランは月額$0で、1バケット、2チームメンバー、1,000オブジェクトを含み、チュートリアルには十分です。無料で始める。
  2. バケットスラッグ、リードキー、ライトキー。手順1で取得方法を説明します。
  3. Claude Codeのインストール。

ホスト型接続ではローカルランタイムは一切不要です。セルフホストのstdioオプションを選択する場合のみ、npx実行のためにNode.jsが必要です。

手順1：バケット認証情報の取得

  1. Cosmicダッシュボードにログイン
  2. バケットに移動
  3. 設定 → APIアクセスに進む
  4. バケットスラッグ、リードキー、ライトキーをコピー

キーを貼り付ける前の推奨事項：まずリードキーのみを使用してください。Cosmicはバケットごとにリードキーとライトキーを分けて発行しているため、Claude Codeにコンテンツの完全な可視性を与えつつ、変更を不可能にできます。セットアップを信頼できたらライトキーを追加してください。読み取り専用とフルアクセスの違いについては後述します。

手順2：ホスト型MCPで接続（推奨）

Claude Codeはリポジトリルートの.mcp.jsonファイルからプロジェクトスコープのMCPサーバーを読み込みます。以下のように作成します：

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

全画面表示 全画面表示を終了

your-bucket-slug、your-read-key、your-write-keyを手順1の値に置き換えます。エンドポイントはstreamable-HTTP MCPトランスポートをサポートします。

認証ヘッダーの仕組み

Cosmicは両方のキーをコロンで区切った単一のBearerトークンとして扱います。コロンの後がライトキーです：

# 読み取り専用アクセス
Authorization: Bearer rk_abc123def456

# フルアクセス（読み取り＋書き込み）
Authorization: Bearer rk_abc123def456:wk_zyx987wvu654

全画面表示 全画面表示を終了

読み取り専用にする場合はコロンとライトキーを省略します。クライアントがコロン区切りのトークンを送信できない場合は、X-Cosmic-Write-Keyヘッダーでライトキーを別途送信できます。

注意：.mcp.jsonには実際の認証情報が含まれるため、次回のコミット前に.gitignoreへ追加してください。

同じmcpServersブロックはClaude DesktopおよびCursorでも使用できます。MCPサーバードキュメントには、各クライアントの設定ファイルパス（macOSの~/Library/Application Support/Claude/claude_desktop_config.jsonやCursorの.cursor/mcp.jsonなど）が記載されています。

手順2（代替）：stdio経由のセルフホスト

自分でサーバーを実行したい場合は、@cosmicjs/mcpパッケージがstdioバイナリを提供します。Claude Codeをnpxに向けます：

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

全画面表示 全画面表示を終了

stdioバイナリは環境変数から認証情報を読み取ります：

  • COSMIC_BUCKET_SLUG（必須）：Cosmicバケットスラッグ
  • COSMIC_READ_KEY（必須）：読み取り操作用のバケットリードキー
  • COSMIC_WRITE_KEY（任意）：書き込み操作用のバケットライトキー

読み取り専用サーバーにする場合はCOSMIC_WRITE_KEYを完全に省略してください。毎回npxで解決する代わりにnpm install -g @cosmicjs/mcpでグローバルインストールすることも可能です。

手順3：接続の確認

Claude Codeを再起動し、以下を実行します：

/mcp

全画面表示 全画面表示を終了

cosmicとそのツールが表示されるはずです。次に、バケットのみが知る内容を依頼して実際に到達できるか確認します：

List all object types in my Cosmic bucket

全画面表示 全画面表示を終了

Claude Codeはcosmic_types_listを呼び出し、実際のコンテンツモデルを返します。オブジェクトタイプが返されれば、接続は有効で正しく認証されています。

18のツールと各ツールの用途

オブジェクト

  • cosmic_objects_list：タイプ、ステータス、ロケールでフィルタリングし、ページネーション付きでオブジェクトをリストまたは検索
  • cosmic_objects_get：IDまたはスラッグで単一オブジェクトを取得（metafield、depth、localeパラメータオプション）
  • cosmic_objects_create：タイトル、スラッグ、ステータス、metafieldを指定して新規オブジェクトを作成（ライトキー必須）
  • cosmic_objects_update：既存オブジェクトのタイトル、スラッグ、ステータス、metafield値を更新（ライトキー必須）
  • cosmic_objects_delete：IDでオブジェクトを完全に削除（ライトキー必須）

メディア

  • cosmic_media_list：メディアファイルをリスト（フォルダ指定可能）
  • cosmic_media_get：単一ファイルのメタデータとimgix URLを取得
  • cosmic_media_upload：URLまたはbase64ペイロードからメディアライブラリへアップロード（ライトキー必須）
  • cosmic_media_delete：メディアファイルを削除（ライトキー必須）

オブジェクトタイプ

  • cosmic_types_list：バケット内の全オブジェクトタイプをリスト
  • cosmic_types_get：metafield、options、ヘルパーテキストを含むオブジェクトタイプの完全なスキーマを取得
  • cosmic_types_create：metafieldスキーマ付きで新規オブジェクトタイプを作成（ライトキー必須）
  • cosmic_types_update：タイプのスキーマまたはmetafield定義を更新（ライトキー必須）
  • cosmic_types_delete：オブジェクトタイプとその全オブジェクトを削除（ライトキー必須）

AI生成

  • cosmic_ai_generate_text：バケット内の既存オブジェクトから取得したコンテキストをオプションで使用してテキストを生成
  • cosmic_ai_generate_image：画像を生成してメディアライブラリに保存（ライトキー必須）
  • cosmic_ai_generate_video：Google Veoで動画を生成してメディアライブラリに保存（ライトキー必須）
  • cosmic_ai_generate_audio：OpenAI TTSでナレーションを生成（13ボイス対応）し、メディアライブラリに保存（ライトキー必須）

エージェント作業で特に有用な2つのツールはcosmic_types_listとcosmic_types_getです。スキーマを読み込んでから書き込むエージェントは、キー名を推測して失敗する代わりに初回で有効なmetafieldを生成できます。

読み取り専用 vs フルアクセス

本番バケットにエージェントを向ける前に正しく理解しておくべき部分です。

読み取り専用トークンを使用すると、全ての書き込みツールは明確なエラーメッセージとともにブロックされ、読み取りツールは通常通り動作します。ブロックされるのは全ての*_create、*_update、*_deleteツールと、生成されたアセットをメディアライブラリに書き込む4つのAI生成ツールです。

したがって、読み取り専用設定でもClaude Codeはコンテンツモデルを探索し、全オブジェクトを読み取り、アプリケーションコードを書きながらコンテンツについて推論できます。ただし、何も変更することはできません。実データに対する初回セッションのデフォルトとして適しています。

実際の使用例

サーバー接続後は、以下はすべて単一のプロンプトで実行できます：

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

全画面表示 全画面表示を終了 

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

全画面表示 全画面表示を終了 

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

全画面表示 全画面表示を終了 

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

全画面表示 全画面表示を終了

スキーマ管理のケースは開発者が過小評価しがちです。通常、コンテンツモデリングはダッシュボード作業ですが、MCPを通じて、それを消費するコンポーネントをスキャフォールディングする同じプロンプトから実行できるようになります。

エージェントスコープ：人間にまだCosmicアカウントがない場合

ホスト型エンドポイントは、エージェントサインアップフロー向けにhttps://mcp.cosmicjs.com/v1/agentで2つ目の小さなスコープを提供します。アカウントを持たない人間に代わってAIエージェントが新しいCosmicプロジェクトとバケットをMCPトランスポート内でプロビジョニングできます。3つのツールを公開します：

  • cosmic_agent_signup（認証不要）： human_emailに紐づく未請求プロジェクトとバケットを作成。agent_key、read_key、write_key、claim_urlを返し、Cosmicは人間に6桁のOTPをメール送信。
  • cosmic_agent_verify（agent_key必須）：OTPを送信し、restricted-modeの制限を解除してAI生成を有効化。
  • cosmic_agent_status（agent_key必須）：請求ステータス、残り制限を確認し、バケットキーを復元。

新規バケットは制限モードで開始されます：AIクレジットなし、オブジェクト最大50、メディア上限5MB。未請求プロジェクトは14日後にハードデリートされます。

前述のバケットスコープツールはエージェントエンドポイントでは利用できず、エージェントツールはバケットエンドポイントでは利用できません。1回の会話で両方を使用することが一般的です：エージェントが人間をサインアップさせ、返されたバケットキーを取得した後、バケットスコープに切り替えてコンテンツ作成を開始します。

MCPサーバー vs Agent Skills

Cosmicは似た名称で異なる役割を持つ2つの機能を提供します：

  • MCPサーバー：直接的なコンテンツ管理用。「ブログ投稿をリストして」と質問すると、AIがバケットに対してツールを呼び出します。
  • Agent Skills：コード生成ガイダンス用。「Cosmicでブログを構築して」と質問すると、AIがSDKを使用してアプリケーションコードを書きます。

両方を使用してください。Agent SkillsはClaude Codeに以下のようなコードを書く支援をします：

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

const cosmic = createBucketClient({
  bucketSlug: 'your-bucket-slug',
  readKey: 'your-read-key',
});

const { objects: posts } = await cosmic.objects
  .find({ type: 'blog-posts' })
  .props(['title', 'slug', 'metadata'])
  .depth(1);

全画面表示 全画面表示を終了

MCPサーバーは、同じセッションでそのコードがレンダリングするコンテンツを管理できるようにします。一方のツールがアプリを書き、もう一方のツールが背後のデータを操作します。

本番バケット向けのガードレール

採用すべき4つの習慣：

  1. まずリードキー。初回の数セッションは読み取り専用トークンで接続し、エージェントの実際の動作を確認してからライトキーを追加します。
  2. 別バケットで実験。バケット許容量はプランに応じてスケールします：Freeは1、Builder（$49/月）は2、Team（$299/月）は3、Business（$499/月）は5。破壊的な実験は失っても問題ないバケットに向けます。
  3. 削除ツールは手動承認のみ。cosmic_objects_delete、cosmic_media_delete、特にcosmic_types_deleteは永続的で、オブジェクトタイプを削除するとその全オブジェクトも削除されます。エージェントに投機的に呼び出させないでください。
  4. シート数を考慮。プランにはチームメンバー数が設定されています（Free 2、Builder 3、Team 5、Business 10）。追加ユーザーは$29/ユーザー/月です。誰がダッシュボードアクセスを必要とするか決定し、デフォルトで全員を追加しないようにします。

トラブルシューティング

サーバーが/mcpに表示されない。.mcp.jsonがリポジトリルートで有効なJSONであることを確認し、Claude Codeを再起動します。一部のClaude Codeバージョンではトランスポートを明示的に指定する必要があります。ホスト型設定が接続できない場合は、urlと一緒に"type": "http"を追加してみてください。

npxがパッケージを見つけられない。パッケージ名は@cosmicjs/mcpで、スコープ付き（@を含む）です。Node.jsがインストールされ、PATHに含まれていることを確認してください。

書き込みツールがエラーを返し、読み取りは動作する。 Bearerトークンにライトキーがありません。ヘッダーがスペースなしでBearer READ_KEY:WRITE_KEY形式であることを確認するか、X-Cosmic-Write-Keyでライトキーを送信してください。

ホスト型エンドポイントから404。URL内のバケットスラッグが間違っています。設定 → APIアクセスから再度コピーしてください。スラッグはプロジェクトの表示名と常に一致するとは限りません。

ツールは接続するが何も返さない。意図したバケットを指していることを確認してください。Claude Codeにcosmic_types_listを実行させ、ダッシュボードの結果と比較してください。

次のステップ

ホスト型エンドポイントと読み取り専用トークンから始めます。Claude Codeにオブジェクトタイプをリストさせ、バケット内のコンテンツを要約させます。動作確認ができたらライトキーを追加してドラフト作成を依頼してください。完全なツールリファレンスとクライアント別設定パスはMCPサーバードキュメントにあります。

実際に試してみる。CosmicはREST API、TypeScript SDK、ホスト型MCPサーバーを備えたAI駆動のヘッドレスCMSです。無料アカウントを作成して約5分でClaude Codeを接続できます。チームでのCosmic評価は、Tonyとの通話予約が可能です。

元々はCosmicブログで公開されました。