メインコンテンツまでスキップ

MCP連携ガイド

このページは、Crate MCP を安全かつ確実に使い始めるための公開ガイドです。
2026年3月5日時点の Crate 提供仕様に合わせて記載しています。

このページで分かること​

  • Crate MCP の最小接続設定
  • 認証方式とスコープの使い分け
  • AGENTS.md/skillなしでも使える運用ガイド取得
  • 利用可能な tool と必須引数
  • よくあるエラーと対処
  • 本番運用時のセキュリティ注意点

1. クイックスタート​

{
  "mcpServers": {
    "crate": {
      "type": "http",
      "url": "https://crateio.com/api/mcp?project_id=<project_id>",
      "headers": {
        "x-crate-ingest-token": "<project_token>"
      }
    }
  }
}

ポイント:

  • エンドポイント: https://crateio.com/api/mcp
  • 推奨認証: x-crate-ingest-token: <project_token>
  • 代替認証: Authorization: Bearer <token>
  • project_id は URL クエリまたは tool 引数のどちらでも指定可能
  • ingest_token / token のクエリ認証は廃止済み（400）

2. 認証とスコープ​

スコープ一覧​

スコープ説明
snapshot:writesnapshot / context / continuity / reindex
issues:readissue 一覧の参照
issues:writeissue の作成・更新・削除（issues:read を内包）

認証評価の順序​

  1. x-crate-ingest-token があれば優先して認可
  2. なければ Authorization: Bearer ... を評価
  3. Bearer は「ユーザーセッショントークン」または「project token」を利用可能

3. Tool仕様​

Snapshot / Continuity（snapshot:write）​

Tool必須引数主な用途
create_snapshotsession_id, occurred_at, conversation_slice, client_event_id, correlation_id履歴を非同期保存
create_contextquery履歴検索（Top3）
get_crate_agent_guideなしCrate運用ガイドを取得（intent + audience で用途を切替）
resolve_session_idsession_id（または mcp-session-id ヘッダー）canonical codex:thread:* session_id を解決
resolve_repo_bindingrepository または github_repo_full_nameproject と GitHub repository の一致確認（複数MCP接続時の判定補助）
get_session_log_detailssession_idproject_id + session_id の共有用 session log details を read-only 取得
get_session_continuitysession_idproject_id + session_id の session log details と継続状態を read-only 取得
upsert_session_continuitysession_id, occurred_at, client_event_id, correlation_id, continuity_state または state継続状態の作成/更新（expected_version 対応）
reindex_snapshotsなしtriage/evidence の再計算（保守用）

create_snapshot の scope は since_last_snap（既定）または recent を指定できます。 create_snapshot / upsert_session_continuity / create_project_issue / delete_project_issue / complete_work_unit では Event Contract v3 のメタデータとして session_id / occurred_at / client_event_id / correlation_id が必須です。update_project_issue は session_id / occurred_at / correlation_id が必須で、client_event_id は通常必須（status=closed のみ context_label を代替根拠として許容）です。context_label / actor_context / source_context も指定できます。

get_crate_agent_guide は次を返します。

  • guide_version / updated_at: ガイドの版情報
  • sections: 原則フロー/例外条件/禁止事項の構造化データ
  • recommended_execution_order: skillなし運用時の推奨手順
  • compact_contract: compaction耐性を高めた実行契約（format=compact で優先取得可能）
    • session_id_canonical_form: codex:thread:<sha256_40hex>
    • idempotency_keys: client_event_id / source_event_id / correlation_id
    • input_contract: MCP送信の共通必須項目・ツール別必須項目・禁止入力
    • timeline_payload_requirements: セッションログ詳細を再構成するためのイベント種別ごとの必須payload

resolve_repo_binding は次を返します。

  • decision: match / mismatch / project_unbound
  • matches: true / false / null
  • can_write_snapshot: match のときだけ true

resolve_session_id は次を返します。

  • session_id: canonical codex:thread:<sha256_40hex>
  • source: mcp_session_id または requested

Issues​

Tool必要スコープ必須引数主な用途
list_project_issuesissues:readなしissue 一覧取得（status / limit で絞り込み可）
create_project_issueissues:writetitle, session_id, occurred_at, client_event_id, correlation_idissue 作成（初期状態は open）
complete_work_unitissues:write + snapshot:writeissue_id, session_id, deliverable.note, deliverable.context_label, deliverable.conversation_slice, client_event_id, correlation_idissue 完了フローを単一操作で実行（snapshot -> checkpoint -> continuity -> close）
update_project_issueissues:writeissue_id, session_id, occurred_at, correlation_id（client_event_id は通常必須、status=closed 時のみ context_label 代替可）issue 更新（status=closed は checkpoint根拠（client_event_id 優先 / context_label 代替）必須。checkpoint pending はサーバー側で短時間待機）
delete_project_issueissues:writeissue_id, session_id, occurred_at, client_event_id, correlation_idissue 削除

Issue status は open / in_progress / closed / canceled です。

project が github_repo_full_name にバインドされている場合、write系（upsert_session_continuity / issue作成更新削除 / reindex_snapshots）は github_repo_full_name（または repository）指定が必須で、不一致は fail-closed します。

4. バリデーション仕様​

session_id の形式​

^[A-Za-z0-9._:@/-]{1,128}$

session系引数はサーバー側で codex:thread:<sha256_40hex> に正規化されます（resolve_session_id / create_snapshot / get_session_continuity / upsert_session_continuity / checkpoint_status / update_project_issue(status=closed) / complete_work_unit）。

  • mcp-session-id ヘッダーがある場合: mcp-session-id を正本に正規化
  • mcp-session-id ヘッダーがない場合: session_id を同じ規則で正規化（Codex thread UUID(v7) を含む）
  • Event Contract v3 対象ツールでは、正規化後の session_id が codex:thread:<sha256_40hex> でない入力を reject する

upsert_session_continuity​

  • client_event_id と correlation_id が必須
  • occurred_at が必須
  • continuity_state（または state）は object 必須
  • 少なくとも1つの非空フィールドが必要
  • expected_version は 0 以上の整数
  • 競合時は status: "version_conflict" を返却

create_snapshot の conversation_slice​

  • 以下の必須項目を構造化 JSON キーで含める
    • decision / reason / assumptions / constraints / pivots / unresolved / next_action
  • context_label と参照URL（https://...）を含める
  • context_label 形式は checkpoint:<note>:<work_slug> を推奨（<note>:<work_slug> も受理）

reindex_snapshots​

  • limit 既定値: 300
  • limit 上限: 2000
  • include_hidden 既定値: true

get_crate_agent_guide​

  • format は full / compact を指定可能（既定: full）
  • audience は mcp / cli を指定可能（既定: mcp）
  • intent は general / read_only / task_create / work_complete / raw_write / recovery / bootstrap_check を指定可能（既定: general）
  • compact は最小契約を返し、LLM compaction後の手順欠落を抑える用途向け
  • Event Contract v3により、クライアントは業務データを送信し、event payload の最終構築はサーバー側allowlistで行う

5. 初回導入の確認手順​

  1. list_project_issues が成功する（issues:read 以上）
  2. get_session_continuity が成功する（snapshot:write）
  3. upsert_session_continuity が status=created または status=updated を返す

この3点が通れば、MCP 接続・認証・基本権限の導線は概ね正常です。

6. エラーと対処​

エラー例原因対処
project_id is required.project_id 未指定URL または tool 引数で指定
session_id is required and must match ...session_id 形式不正許可文字で再指定
ingest_token/token query parameters are no longer supported...廃止されたクエリ認証を利用x-crate-ingest-token へ移行
issue ... failed: status=403scope 不足 / 権限不足issues:write 付与または権限見直し
Unauthorized (401)無効・失効・期限切れ tokentoken 再発行

7. セキュリティ運用の推奨​

  • token は最小権限で発行する（必要な scope のみ）
  • token は共有しない（個人チャット・Issue本文への貼り付け禁止）
  • 不要な token は速やかに失効し、定期ローテーションする
  • 本番運用は HTTPS を前提にする
  • 外部 MCP を併用する場合は、導入元の信頼性と権限範囲を事前確認する

8. 複数Crate MCP接続時の判定​

Codex などで複数の Crate MCP が同時接続される場合は、write 実行前に次を推奨します。

  1. git remote から owner/repo を取得
  2. 各 MCP に resolve_repo_binding を同じ repo で実行
  3. decision=match の接続のみ write を許可
  4. 0件 または 複数件 の場合は曖昧として中断

参考​