エージェントの接続

ochakai をセットアップしたら、各種 AI エージェントからナレッジを検索・参照できるように接続します。接続方法は、サーバー側の認証要件（Cloud Run の IAM 認証など）と、クライアントの実行環境によって決まります。

本ガイドは ochakai v0.31.1 に対応しています。詳細は公式リポジトリの MCP クライアント接続ガイド・CLI リファレンス・Claude Code 連携設定例も参照してください。サーバーの構築手順は「デプロイと運用ガイド」をご覧ください。

0. 接続形式の選び方（直接 URL かブリッジか）

ochakai への接続形式は、主にサーバーの認証要件によって 2 つに分かれます。

• 直接 URL 接続: 認証が不要な公開デモ（demo.ochak.ai）やローカル開発環境（dev）など、追加の IAM トークンを必要としない環境で使用します。クライアントの設定にサーバーの URL を直接指定します。
• ブリッジ接続（ochakai mcp-stdio）: Google Cloud IAM 認証で保護された Cloud Run などの本番環境で使用します。一般的な MCP クライアントは Google の ID トークンを自動発行できないため、ローカルで動作する ochakai mcp-stdio をプロキシ（ブリッジ）として起動し、通信を中継させます。

ブリッジはローカルの gcloud セッションから ID トークンを安全に取得してサーバーへリクエストを転送します。API キーや秘密情報を設定ファイルに平文で保存する必要はありません。現在接続先がどのモードで動いているかは、ochakai whoami コマンドの posture: 行で確認できます。

ブリッジコマンドを起動する形式では、クライアントが動作するマシンの PATH 上に ochakai バイナリがインストールされている必要があります。さらに Cloud Run に接続する場合は、以下の 2 点が前提となります。

• gcloud CLI が導入されていること: ID トークンの発行に必要です。
• gcloud auth login が完了していること: 対象の Cloud Run サービスに対する呼び出し権限（roles/run.invoker）を持つアカウントでログインしてください。

設定前に、ターミナルで以下のコマンドを実行して接続状態を確認しておくことをおすすめします。

ochakai whoami

1. Claude Code

Claude Code では、MCP よりも CLI 経由での利用を推奨しています。シェル環境を備えているため、CLI を直接呼び出すことでコンテキスト枠を節約できます。また、Cloud Run への認証も CLI 自体が行うため、ブリッジプロセスの常駐が不要です。

ochakai use https://your-service.run.app   # 接続先サーバーを設定（マシンごとに一度）
ochakai whoami                             # 接続先と認証ユーザーを確認
ochakai search "なぜ売上が落ちている?"       # ナレッジを検索

認証は事前に行った gcloud auth login のセッションがそのまま利用されます。

claude mcp add --transport http ochakai http://localhost:8080/mcp

claude mcp add --transport http ochakai https://demo.ochak.ai/mcp

claude mcp add ochakai -- ochakai mcp-stdio

2. Claude Desktop

配布されている MCP バンドルを利用するのが最も簡単です。リリースページから ochakai_0.31.1.mcpb を入手して開きます。Claude Desktop にワンクリックで登録でき、公開デモの URL も自動設定されます（macOS / Windows 対応）。

自前でデプロイした Cloud Run に接続する場合は、上述の通りマシン側で gcloud auth login を済ませておくだけで、バンドル内のブリッジが自動的に認証を解決します。

手動で設定ファイルに記述する場合は、設定ファイルを開いて以下のように設定します。

{
  "mcpServers": {
    "ochakai": { "command": "ochakai", "args": ["mcp-stdio"] }
  }
}

設定ファイルは、macOS では ~/Library/Application Support/Claude/claude_desktop_config.json にあります。Windows では %APPDATA%\Claude\claude_desktop_config.json です（設定メニューの Edit Config からも開けます）。編集後はアプリを再起動してください。

デスクトップアプリはターミナルの PATH を引き継がない場合があるため、command には絶対パス（例: /usr/local/bin/ochakai）を指定することをおすすめします。サーバー URL を明示的に指定する場合は --url 引数を追加します。

{
  "mcpServers": {
    "ochakai": {
      "command": "/usr/local/bin/ochakai",
      "args": ["mcp-stdio", "--url", "https://your-service.run.app"]
    }
  }
}

.mcpb か、Claude のコネクタか

Claude からの接続経路は 2 つあり、それぞれ別のデプロイに向いています。コネクタは Anthropic のインフラから接続を開きます。トークンを自分で検証するデプロイ（OCHAKAI_OIDC_ISSUER）なら、利用者はブラウザで Google Workspace にサインインして届きます。

迷ったら、公開到達を受け入れられるかで決めます。受け入れられるならコネクタ 1 つで全員に届き、バンドルは要りません。受け入れられないなら、バンドルと Claude Code が使える経路のすべてです。ochakai は secret を持ちません。OAuth クライアントの secret は Claude の組織設定に入ります。手順は製品ドキュメントの Cloud Run デプロイ手順 §5e にあります。

公開デモのように identity を読まないデプロイには、サインインが要りません。カスタムコネクタの URL に https://demo.ochak.ai/mcp を入れ、OAuth の欄を空のまま追加するだけで、claude.ai から届きます。

3. その他のクライアント（Cursor, VS Code 等）

Cursor や VS Code などの各種エディタでも同様に接続できます。設定ファイル内のキー名がエディタごとに異なる点だけご注意ください。直接 URL 形式の場合は http://localhost:8080/mcp や公開デモの URL を指定し、ブリッジ形式の場合は ochakai mcp-stdio を指定します。

ブリッジ形式の場合は、command: "ochakai" および args: ["mcp-stdio"] を指定します（VS Code は "type": "stdio" も併記）。

4. 想起と書き戻しの自動化（Claude Code フック）

MCP サーバーを接続しただけでは、エージェントが自発的にナレッジベースを検索しに行くとは限りません。Claude Code 向けには、ナレッジの想起（Recall）と書き戻し（Write-back）を完全自動化するフックが用意されています。

• CLAUDE.md: プロジェクトのルールとして、エージェントに ochakai コマンドの存在と知見の書き戻しを指示します。
• hooks/: Claude Code のライフサイクルイベントに合わせて自動実行されるスクリプトです。プロンプト送信時や作業終了時に確実に呼び出されます。

同梱されているフックは以下の 2 つです。

• ochakai-recall.sh（UserPromptSubmit 時）: ユーザーがプロンプトを入力した直後に ochakai search "<prompt>" --json を実行し、関連ナレッジのインデックス情報をコンテキストへ自動注入します。ナレッジの要約と ID のみを渡すためトークン消費は最小限に抑えられ、本文が必要な場合のみエージェントが取得します。
• ochakai-write-back.sh（Stop 時）: エージェントが作業を完了した直後に割り込み、再利用可能なクエリや新たな発見があった場合に、Draft ナレッジとして書き戻すかどうかをユーザーに確認します。

# CLI の接続先を設定（マシンごとに一度）
ochakai use https://your-service.run.app

# プロジェクトのリポジトリにフックスクリプトをダウンロード
mkdir -p .claude/hooks
base=https://raw.githubusercontent.com/na0fu3y/ochakai/v0.31.1/examples/claude-code/hooks
curl -L -o .claude/hooks/ochakai-recall.sh     $base/ochakai-recall.sh
curl -L -o .claude/hooks/ochakai-write-back.sh $base/ochakai-write-back.sh
chmod +x .claude/hooks/ochakai-*.sh

ダウンロード後、プロジェクトの .claude/settings.json に以下の設定を追加します。

{
  "hooks": {
    "UserPromptSubmit": [
      { "hooks": [ { "type": "command", "timeout": 15,
        "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/ochakai-recall.sh" } ] }
    ],
    "Stop": [
      { "hooks": [ { "type": "command", "timeout": 10,
        "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/ochakai-write-back.sh" } ] }
    ]
  }
}

詳細なスクリプト内容や CLAUDE.md のサンプルテンプレートは examples/claude-code をご覧ください。フックの実行には jq コマンドが必要です。

5. エージェントが利用する 6 つの MCP ツール

これらのツールはナレッジの検索・取得・記録のみを行い、SQL の実行も LLM の呼び出しもしません。デプロイが任意で有効にするデータエージェントは Web UI と REST だけの機能で、MCP には出てきません。また、安全な設計として読み取り系ツールには readOnly アノテーションが付与されています。

6. トラブルシューティング

接続できないクライアントについて

ChatGPT のコネクタなど、クラウド側から直接接続を試みる外部サービスは、IAM 認証された Cloud Run には到達できません。安全に利用できるのは、Claude Code や Cursor など手元のマシンで動作するクライアントです。Claude だけは例外で、コネクタが Google のサインインで届きます。

よくある問題と解決策

• ツールが一覧に表示されない: ブリッジが起動できていないか、PATH 上に ochakai が見つかっていない可能性があります。ターミナルで which ochakai を確認し、設定ファイルの command に絶対パスを指定してください。
• ツールは表示されるが、実行時にエラーになる: Cloud Run の IAM 認証エラーの可能性があります。ターミナルで gcloud auth login を実行し、該当サービスに対する roles/run.invoker 権限があるか確認してください。
• curl では応答があるが、MCP 接続できない: エンドポイントのパスを確認してください。MCP のエンドポイントは /mcp です。

ブリッジ（ochakai mcp-stdio）は詳細なログを標準エラー出力（stderr）に出力します。その他のトラブルシューティングは公式ドキュメントの Troubleshooting ガイド をご覧ください。

次のステップ

エージェントが接続できたら、次はナレッジベースに実際の知識を登録していきましょう。「ナレッジ作成ガイド」では、初期データの取り込みから効果的なドメイン知識の記述手順を解説しています。