ClaudeのカスタムコネクタでつないだosFoundryの接続を一段ずつ確認する

この記事でやること

• claude.aiのカスタムコネクタでosFoundryにつないだあと、「どこまで届いているか」を段階ごとに確かめる
• 確かめる順番は、サーバーアドレス → 接続の状態 → プロジェクト → チャンネル → 書き込みと承認 → 切り方
• 各段階で、Claudeに投げると確認しやすい依頼文と、osFoundry側で見る画面をセットで書く

接続の作り方そのもの（鍵アイコン → Connected → Add assistant → Claudeでコネクタ追加）は済んでいる前提です。

前提・環境

• osFoundryのアカウントと、接続したいワークスペースが1つある
• claude.aiでカスタムコネクタを追加できるプラン。Team / Enterpriseでは、組織のオーナーが先に Organization settings → Connectors で追加している
• ターミナルで curl と python3 が使える（最初の確認だけで使います）
• サーバーアドレスは本番の次のURL

https://api.osfoundry.io/api/v1/external-mcp

確認1 サーバーアドレスが生きているか

コネクタの追加で詰まったら、まずアドレスそのものを疑います。このサーバーは、サインイン前でも initialize と tools/list には答えます。トークンが要るのはツールの実行（tools/call）だけです。なので、curlで叩けば「アドレスの打ち間違い」かどうかはすぐ分かります。

check-endpoint.sh

URL=https://api.osfoundry.io/api/v1/external-mcp
H1='content-type: application/json'
H2='accept: application/json, text/event-stream'

# 1) ハンドシェイク。200とserverInfoが返ればアドレスは正しい
curl -s -w '\n%{http_code}\n' -X POST "$URL" -H "$H1" -H "$H2" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18","capabilities":{},
                 "clientInfo":{"name":"curl-check","version":"0"}}}'

# 2) ツール一覧の件数とスコープ別の内訳
curl -s -X POST "$URL" -H "$H1" -H "$H2" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' |
python3 -c 'import sys,json,collections
t=json.load(sys.stdin)["result"]["tools"]
print(len(t), collections.Counter(s["scopes"][0] for x in t for s in x.get("securitySchemes",[])))'

2026-11-06に東京のMacから叩いた結果はこうでした。

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18", ...
 "serverInfo":{"name":"osfoundry","version":"0.1.0"},
 "instructions":"Use list_granted_resources first. Every Note edit must use the exact tab ID. Local-only data is unavailable to cloud clients."}}
200
59 Counter({'osfoundry:read': 30, 'osfoundry:write': 26, 'osfoundry:run': 3})

ここで200が返っていれば、アドレスは合っています。あとはClaude側の設定かosFoundry側の接続を見る番です。なお、ツール一覧にはユーザーのデータは入っていません。中身を確かめるのはサインイン後です。

確認2 接続の状態表示を読む

osFoundryで鍵アイコン → Connected を開き、作った接続を選びます。表示される文言で、いまどの段階にいるかが分かります。

表示	意味	次にやること
「Setup pending. This assistant cannot read or change anything yet.」	接続は作ったが、Claude側からの承認がまだ	ClaudeでコネクタのConnectを押す
「Connected.」	ワークスペースへの承認まで済んだ	Projects でプロジェクトを足す
プロジェクト欄が空	新しい接続はプロジェクト0件から始まる仕様	Add to project

Connectを押したときの承認画面（https://osfoundry.io/external-assistant-authorize）は、見落としやすい項目が2つあります。

• Connection：「Use pending: <表示名>」を選ぶと、先に作った接続に紐づきます。「Create a new connection」のままにすると、別の接続がもう1つ増えます。Connectedタブに同じClaudeの接続が2つ並んでいたら、ここが原因です
• Workspace to connect：選べるのは1つだけです。別のワークスペースも使うなら、接続をもう1つ作ります

確認3 プロジェクトが見えているか

Claudeの会話で + メニュー → Connectors からosFoundryのコネクタをオンにし、次のように頼みます。

確認用の依頼文

osFoundryで、いまアクセスできるプロジェクトを一覧して。
それぞれのプロジェクトで見えるリソースの種類も教えて。

サーバーの instructions にあるとおり、Claudeはまず list_granted_resources を呼び、続けて list_project_resources でプロジェクトの中身を見に行くはずです。以下は表示例です。

表示例

Claude → list_granted_resources {}
       ← 接続済みプロジェクト1件:「Launch Q3」
Claude → list_project_resources {"project_id": "…"}
       ← ノート 4件、ナレッジベース 1件、Recordチャンネル 1件

Claude: いま見えるのは「Launch Q3」の1件です。ノート4件、ナレッジベース1件、
        Recordチャンネル1件があります。

ここで「プロジェクトが0件」と返ってきたら、確認2のプロジェクト欄に戻ります。プロジェクトに足したあとは、そのプロジェクトのノート、ナレッジベース、Recordチャンネル、クラウドのRoom、割り当て済みのGitNestリポジトリ、ディスカッションチャンネルに届きます。あとからプロジェクトに入れたものも対象になります。

逆に、見えないのが正しいものもあります。

• ローカルのRoom、ローカルのGraphセッション、同期していないコンテンツ。サーバーが initialize で返す「Local-only data is unavailable to cloud clients.」のとおりです
• 別のプロジェクトにあるアイテム。権限はサインイン時ではなく呼び出しごとに確かめるので、ノートを別プロジェクトへ移すと次の呼び出しから見えなくなります
• 接続を承認した本人に編集権限がないアイテムの編集

確認4 Messageチャンネルに届いているか

プロジェクトに入って自動で開くのは、そのプロジェクトのディスカッションチャンネルだけです。普通のMessageチャンネルは招待制なので、Claudeから見えなくても設定が足りないわけではありません。

接続の画面で Message channels → Choose a Message channel → Invite と進み、チャンネルごとに招待します。プライベートチャンネルはオーナーが招待します。招待したら、次の依頼で確かめます。

確認用の依頼文

osFoundryで、このコネクタから読めるMessageチャンネルを教えて。

確認5 書き込みと承認の流れ

書き込みは2種類あり、承認の場所が違います。最初は小さな書き込みで両方を一度ずつ通しておくと、運用中に迷いません。

種類	例	承認する場所
直接の編集	edit_record_item でレコードのstatusを変える	Claude自身のツール許可ダイアログ
提案	GitNestのタスク、change set、ファイル取り込み、プルリクエスト、Roomへのアプリ追加（propose_… 系）	osFoundryのConnectedタブの「Needs your approval」

直接の編集を試すなら、Recordのアイテムを1つ用意して頼みます。

確認用の依頼文

osFoundryの「料金ページ」のレコードを読んで、statusを Ready にして。
変更前と変更後のstatusも書いて。

Claudeは read_record_item でversionを取り、そのversionを expected_version に入れて edit_record_item を呼びます。間で誰かが書き換えていれば、上書きはされずに弾かれます。同じ idempotency_key での再送は最初の結果を返すので、Claudeがリトライしても二重には書き込まれません。

提案系を試したときは、Claudeのチャットで完了と言われても、まだ反映はされていません。Connectedタブの「Needs your approval」に並んだものを開き、対象のリポジトリやRoom、ファイルを見てから Approve か Decline を押して、そこで初めて確定します。GitプロバイダーのトークンやシークレットはClaudeに渡りません。

確認6 Recent activityで呼び出しを突き合わせる

接続ごとのRecent activityには、Claudeが呼んだツールが残ります。確認3〜5で頼んだ内容と、ここに並ぶ呼び出しを突き合わせておくと安心です。チャットの回答だけを見て判断するより確実です。

特に見ておきたいのは次の2点です。

• 読むだけのつもりの依頼で、書き込み系のツールが呼ばれていないか
• 書き込みを頼んだ回数と、実際に保存された回数が合っているか

ツールの範囲を狭めたいときは、接続画面の Tools で外して Save tools を押します。初期状態は「All supported tools are on by default.」です。

確認7 止め方と切り方を一度試す

運用を始める前に、止める操作も一度やっておくと安心です。どれも次の呼び出しから効きます。

やりたいこと	操作
特定のプロジェクトだけ見せなくする	接続からそのプロジェクトを外す
特定のツールだけ使わせない	Tools で外して Save tools
接続そのものを止める	Revoke connection

外したあとで、確認3の依頼文をもう一度投げます。外したプロジェクトが一覧から消えていれば、権限の判定が呼び出しごとに効いていることを自分の目で確かめられます。

よくある疑問

osFoundryの側からClaudeに通知は来ますか

来ません。MCPでつなぐと、Claudeが必要だと判断したときにosFoundryのツールを呼べるようになります。逆向き、つまりosFoundryが個人の会話を一覧したり、読んだり、始めたりするAPIはありません。動くのは、会話を開いて頼んだときです。

ChatGPTからも同じアドレスでつなげますか

つなげます。ChatGPTの開発者モードのMCP接続も、同じサーバーアドレスで、同じ401のヘッダーをたどってログイン画面まで進みます。

Claude Codeから使うとツール名が変わるのはなぜですか

同じURLをClaude Codeに osfoundry という名前で登録すると、Claude Codeがサーバー名を接頭辞に付けるからです。list_project_resources は mcp__osfoundry__list_project_resources として見えます。中身は同じツールです。

ナレッジベースの回答の出典はどう確かめますか

search_knowledge_base は記事IDと最終更新日時を返します。「記事名と更新日も添えて」と頼んでおけば、回答の横で出典を確かめられます。ナレッジベースの構成はosFoundryのナレッジベースの紹介ページにあります。

まとめ

• アドレスの確認はcurlで十分です。initialize と tools/list は、サインイン前でも返ってきます
• 「何も見えない」は、たいていプロジェクト0件かMessageチャンネル未招待のどちらかです
• 書き込みはClaude側で承認するものと、osFoundryの「Needs your approval」で承認するものに分かれます
• 外す・Revokeする操作は次の呼び出しから効くので、運用前に一度試しておきます