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

Codex導入ガイド（Crate向け）

このページは、エンドユーザーが Codex で Crate を運用開始するための実践ガイドです。
2026年2月17日時点の公開手順に合わせて記載しています。

このガイドで扱う内容:

  • MCP 接続設定（仕様準拠）
  • Crate 用 skill の導入（公開repoベース）
  • AGENTS.md への Crate 運用ルール追記

1. 導入前チェック​

  • Crate の project_id を確認済み
  • MCP token（x-crate-ingest-token 用）を発行済み
  • Codex が利用可能
  • ~/.codex/config.json と ~/.codex/AGENTS.md を編集できる

2. MCP 接続設定​

~/.codex/config.json に Crate MCP を登録します。

{
  "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 を使用します
  • LP/ドキュメントの公開URLは https://try.crateio.com ですが、MCP API は https://crateio.com/api/mcp です
  • project_id は URL クエリか tool 引数で指定できます
  • ingest_token / token クエリ認証は廃止済みです

3. Crate 用 skill を導入​

公開配布リポジトリ: arrhq/crate-codex-skills

導入で使う実体ファイル:

方法A: Codex に導入を依頼（推奨）​

Codex に次を渡してください。

https://github.com/arrhq/crate-codex-skills/tree/main/codex/skills/crate を参照して、crate skill をインストールしてください。

方法B: スクリプトで導入​

git clone https://github.com/arrhq/crate-codex-skills.git
cd crate-codex-skills
./scripts/install.sh

AGENTS.md 追記まで自動化する場合:

./scripts/install.sh --append-agents

このスクリプトの動作:

  • ./scripts/install.sh: ~/.codex/skills/crate を配置
  • --append-agents 付き: ~/.codex/AGENTS.md にテンプレートを追記（重複防止マーカー付き）

方法C: 手動で配置（スクリプトを使わない）​

git clone https://github.com/arrhq/crate-codex-skills.git
mkdir -p ~/.codex/skills
cp -R crate-codex-skills/codex/skills/crate ~/.codex/skills/crate

AGENTS.md は crate-codex-skills/templates/AGENTS.crate.md の内容を手動で追記してください。

4. AGENTS.md 追記​

推奨: テンプレートをそのまま利用します。
参照: templates/AGENTS.crate.md

要点は次の5つです。

  • Continuity: get_session_log_details / get_session_continuity / upsert_session_continuity
  • Issue: list_project_issues / create_project_issue / update_project_issue
  • Completion: 標準フローは complete_work_unit を第一選択とし、update_project_issue(status=closed) は障害時の low-level 整合回復でのみ使う
  • Snapshot: チェックポイントで create_snapshot
  • Context: 履歴説明時に create_context

5. 導入後の受け入れ確認​

Codex で次を順に実行し、4つとも成功することを確認します。

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

6. よくあるつまずき​

症状典型原因対処
401 Unauthorizedtoken 無効/失効token を再発行
403 Forbiddenscope 不足issues:read / issues:write を見直し
404 Not Foundhttps://try.crateio.com/api/mcp を使用https://crateio.com/api/mcp へ修正
issue 操作だけ失敗snapshot:write のみ付与issues:read または issues:write を追加

7. 運用のベストプラクティス​

  • skill 配布は組織管理リポジトリで行う
  • token は最小権限で発行し、定期ローテーションする
  • AGENTS.md は運用ルールの正本として PR レビュー対象にする
  • issue（実行対象）と continuity（判断ログ）を混ぜない

8. 複数Crate MCPを同時接続する場合​

ローカルマップを持たずに安全運用する場合は、次の手順を推奨します。

  1. git remote get-url origin から owner/repo を取得
  2. 候補の Crate MCP それぞれへ resolve_repo_binding を同じ repo で実行
  3. decision=match の接続だけを write（create_snapshot）に使う
  4. match が 0件または複数件なら曖昧なので write を中断

参考​