エージェントを繋ぐ

ochakai を立てたら、次はエージェントから読める状態にします。設定に何を書くかは、サーバーがどこにあるかと、クライアントがコマンドを起動できるか URL を開けるかで決まります。

内容は v0.27.5 時点のものです。元にしているのは製品リポジトリの MCP クライアントの繋ぎ方・CLI リファレンス・Claude Code の例で、細かい分岐はそれぞれの原文にあります。立てるところまでは、もう 1 つのガイド「立てて、運用する」です。

0. Cloud Run に届くために

規則は 1 つです。ローカルのサーバーで、URL を開けるクライアントなら URL。それ以外はすべてブリッジです。Cloud Run に対しては例外なくブリッジです。すべてのリクエストが Google の ID トークンを運ばなければならず、それを発行できる MCP クライアントは 1 つもありません。

ブリッジは ochakai mcp-stdio です。stdin/stdout で MCP を話し、他のクライアントコマンドと同じ方法で identity を解決して、JSON-RPC メッセージをそのまま転送します。資格情報は gcloud のセッションにあり、クライアントの設定ファイルにも、ochakai がローテーションしなければならないディスク上にも置かれません。

クライアント	ローカル `docker compose`	Cloud Run	設定の置き場所
Claude Code	URL	ブリッジ	`.mcp.json`、または `claude mcp add`
Claude Desktop	ブリッジ	ブリッジ	`claude_desktop_config.json`
その他のクライアント	URL	ブリッジ	クライアントごと(§3)
ホスト型アシスタント	—	—	設計上、届かない

Claude Code だけは、MCP を使わない 3 つ目の経路を持ちます(§1)。ローカルの URL は http://localhost:8080/mcp で、deploy/compose.yaml が渡すものそのものです。

コマンドを起動する設定はどれも、クライアントの PATH 上に ochakai を必要とします。Cloud Run に対してはさらに 2 つ要り、どちらもマシンに既定では入っていません。

gcloud CLI。ID トークンの出どころです。ブリッジはまずサービスアカウントの ADC を試し、それが無ければ gcloud auth print-identity-token にフォールバックします。ユーザー自身の application-default credentials では Cloud Run が求める audience 束縛のトークンを発行できないため、個人のマシンで動くのは gcloud の経路です。
gcloud auth login を済ませていること。そのサービスに対する roles/run.invoker を持つ principal としてです。

設定を編集する前に、端末でこれを走らせてください。どのサーバーに誰として話しかけていて、それが応答するかを表示します。

ochakai whoami

1. Claude Code

推奨は CLI で、MCP ではありません。Claude Code はシェルを持つため、CLI のツールスキーマはエージェントのコンテキストを消費しません。--help はその場で読めます。Cloud Run に対しても、ID トークンを自分で解決するため、プロキシやブリッジのプロセスが要りません。

ochakai use https://your-service.run.app   # サーバーを選ぶ。マシンごとに一度
ochakai whoami                             # どのサーバーに、誰として、届くか
ochakai search "なぜ売上が落ちている?"       # データの問いは、ここから始まる

認証は §0 のとおり gcloud auth login だけです。

それでも MCP のツールとして繋ぐ

ローカルサーバーに対して:

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

Cloud Run に対して、ブリッジ経由:

claude mcp add ochakai -- ochakai mcp-stdio

-s user はプロジェクトではなくユーザーの設定に置く。既定のスコープは、プロジェクトディレクトリに閉じたローカル。-s project は .mcp.json に書き込む。これはコミットされる形のため、チームで共有するサーバーを指すときに使う。

2. Claude Desktop

バンドルが一番早い経路です。リリースページの ochakai_0.27.5.mcpb を開くと、アプリがそれをインストールし、訊いてくるのはサーバーの URL 1 つだけです。公開デモが既定で入っているため、そのまま確定すれば繋がります。中身は下の JSON と同じブリッジで、書く手間が省けるだけです。バンドルを入れられるのは macOS と Windows です。

バンドルに入っているのは ochakai のバイナリだけです。Cloud Run に対しては §0 がそのまま要ります。公開デモと、IAM の後ろに居ないデプロイは、バンドルだけで動きます。

自分で書く場合。デスクトップアプリの設定ファイルはコマンドを取るため、ローカルでもブリッジです。

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

ファイルは macOS では ~/Library/Application Support/Claude/claude_desktop_config.json にあります。Windows では %APPDATA%\Claude\claude_desktop_config.json です。設定 → Developer → Edit Config が開いてくれます。編集したらアプリを再起動します。

command には絶対パスを使ってください(which ochakai)。デスクトップアプリはシェルの PATH を継承しないため、正しく見える設定がツールを 1 つも出さないのは、たいていこれが理由です。ochakai use で選んだのと違うサーバーを使うときは --url を足します。

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

アプリのカスタムコネクタ UI は URL を取りますが、その接続はあなたのマシンではなく Anthropic のインフラから開かれます(§6)。

3. その他のクライアント

2 つの形はどのクライアントでも同じで、違うのは JSON のキー名だけです。入れる場所は次の器です。URL 形式は §0 の http://localhost:8080/mcp を、ブリッジ形式は §2 の command / args をそのまま使います。

クライアント	設定の置き場所	URL 形式の器
Cursor	`~/.cursor/mcp.json`(全プロジェクト)、`.cursor/mcp.json`(1 つ)	`mcpServers` → `url`
VS Code	`.vscode/mcp.json`、または MCP: Open User Configuration	`servers` → `type: "http"` と `url`
Windsurf	`~/.codeium/windsurf/mcp_config.json`	`mcpServers` → `serverUrl`
Cline	MCP Servers → Configure MCP Servers(ドキュメントとソースがパスで食い違うため、パネルから開く)	`mcpServers` → `type: "streamableHttp"` と `url`
Zed	`~/.config/zed/settings.json`	`context_servers` → `url`
Gemini CLI	`~/.gemini/settings.json`、またはプロジェクトごとの `.gemini/settings.json`	`mcpServers` → `httpUrl`

ブリッジ形式はどれも url の項目を command / args に置き換えたもので、VS Code だけ "type": "stdio" を添えます。

キー名を間違えると黙って失敗します。Gemini CLI の url は SSE を意味するため /mcp に向けると原因の分からない形で落ち、Cline は type の綴りを間違えると黙って SSE にフォールバックします。この 2 つは §6 より先に疑ってください。

この 6 つは各クライアント自身のドキュメントから 2026 年 7 月時点で写したものです。正はそれぞれのクライアントのドキュメントです。

4. 想起と書き戻しを自動にする

繋いだだけでは、エージェントは知識ベースを見に行く習慣を持ちません。Claude Code には、それを自動にするフックが同梱されています。効き方の弱い順に、2 つあります。

CLAUDE.md。エージェントにコマンドと「学んだことを書き戻す」習慣を教えます。内容を自分のプロジェクトの CLAUDE.md にコピーします。指示はエージェントが覚えていることに頼るため、遵守は完全ではありません。
hooks/。ループを自動にします。フックを実行するのは Claude Code 自身のため、毎回必ず発火し、エージェントの判断が挟まりません。

フックは 2 つです。

ochakai-recall.sh(UserPromptSubmit)は ochakai search "<prompt>" --json を実行し、返ってきた順位を、エージェントが作業を始める前にコンテキストへ差し込みます。差し込むのは id・型・trust・説明のポインタ行だけで、知識の本体は入れません。取りに行くかどうかは、エージェント自身の選択です。
ochakai-write-back.sh(Stop)はエージェントが止まる直前に割り込み、再利用できるクエリと気づきを保存するか、想起で指されたドキュメントが実際に持ちこたえたかを訊きます。どちらでもないと判断させることもできます。

# マシンごとに一度: CLI を自分のサーバーに向ける
ochakai use https://your-service.run.app

# プロジェクトごとに、2 つのスクリプトを置く
mkdir -p .claude/hooks
base=https://raw.githubusercontent.com/na0fu3y/ochakai/v0.27.5/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

あとは、この hooks キーをプロジェクトの .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 が要り、失敗しても黙ります。届かない知識ベースが、プロンプトや停止を塞ぐことはありません。

つまみは OCHAKAI_RECALL_LIMIT 1 つで、想起フックが差し込むポインタ行の最大数です。既定は 8。フックはエージェントのコンテキストウィンドウを使うため、この 1 つがよく効きます。上限に達すると印字をやめ、いくつ残したかを言います。下げて失うのは到達範囲で、正しさは変わりません。

想起フックはスラッシュコマンドを飛ばします。書き戻しフックは、トランスクリプトがデータ作業に見える(SQL や ochakai の利用がある)セッションでのみ、しかもセッションごとに最大一度だけ発火します。

5. エージェントが手にする 6 つのツール

ツール	何をするか
`search_concepts`	型をまたいだ検索。verified なドキュメントが上位に来る。順位のため `limit` で終わり、二ページ目は無い。データの質問はここから始める
`list_concepts`	レビューのフィードを端まで歩く(`verified_at` / `usage` / `failed` / `stale_after`)。`cursor` で続きを引く。検索ではないので `query` は取らない
`get_concept`	ドキュメントを一件、OKF の形で取得する。ファイルのメタデータと、このドキュメントを本文から指すドキュメントの行(`linked_from`)が付く
`get_file`	ドキュメントに添付されたファイルを取得する。ダッシュボードのスクリーンショット、ER 図など
`put_concept`	学びを書き戻す。id が空いていれば作成し、埋まっていれば置き換える。変更はすべてリビジョンとして残る
`report_outcome`	知識をもとに行動した後、worked / failed を報告する。failed の報告は、検証済みのドキュメントを再検証のフィードに乗せる

これらはすべて知識に関する操作です。ochakai は SQL を実行せず、LLM も呼びません。読み取り系のツールには readOnly の、書き込み系には destructive: false のアノテーションが付いているため、クライアントの自動承認ポリシーは説明文を解析しなくても機能します。

削除と利用回数の合計は、この表にありません。削除は人の判断で、利用回数はループの人間側にあります。REST は DELETE /api/v1/bundle/{path} と GET /api/v1/usage/{id} です。CLI は ochakai delete と ochakai usage、web UI にも残っています。

すべてのドキュメントは MCP リソースでもあります。ochakai:// の後ろに id を続けた URI で、たとえば ochakai://metrics/revenue です。リソース参照(@ メンション)に対応するクライアントは、ツール呼び出し無しでドキュメントを引き込めます。見つける手段は、引き続き search_concepts です。

ツール数は REST の写しではありません。ツールスキーマはエージェントのコンテキストを占めるため、6 つに絞ってあります。全機能が要るなら REST API か、シェルを持つエージェントには CLI です。

6. 届かないクライアントと、繋がらないとき

デプロイに届かないクライアント

ChatGPT のコネクタ、OpenAI の Responses API、Claude Desktop のカスタムコネクタ UI。いずれも接続をあなたのマシンからではなくベンダーのインフラから開きます。そこから localhost や IAM で制限された Cloud Run サービスには届かず、どんな設定の書き方もそれを変えません。

到達できることそのものが認可であるため(「立てて、運用する」§4)、第三者のサーバーから届くようにすることは、公開到達可能にすることと同じです。サポートされる経路は、ローカルのコードを動かせるクライアント、つまりブリッジ越しの Claude Desktop・Claude Code・Cursor です。

繋がらないとき

ツールが 1 つも出ず、エラーも出ない。クライアントはブリッジを起動したものの、ブリッジがサーバーに届かなかったか、ochakai がクライアントの PATH に無かったかです。端末で ochakai whoami を走らせ、その上で command に絶対パスを使ってください。
ツールは出るが、呼び出しがすべて失敗する。たいていは identity の問題です。Cloud Run に対してはブリッジが gcloud auth login を済ませている必要があり、呼び出し元は roles/run.invoker を持っている必要があります(§0)。
サーバーは curl には応答するが、クライアントには応答しない。パスを確認してください。/mcp であって、ルートではありません。ochakai サーバーへの GET / は、それが提供するエンドポイントを表示します。
ドキュメントがあるはずの知識ベースで、検索が空を返す。接続の問題ではありません。日本語の知識ベースは埋め込みを有効にしておきたいところで、その切り替えは「立てて、運用する」§5 です。

ochakai mcp-stdio は診断情報を stderr に書き、stdout はプロトコル専用に残します。サーバーのログを表示するクライアントなら、ブリッジが見たものをそのまま読めます。残りの症状は、トラブルシューティングにあります。

次は

次は、そこに入れるものです。空の知識ベースから始めるなら「最初のひと月」が、範囲の決め方と何をどの順で書くかを扱います。