Cursor / Claude から使う（MCP 連携）

Cursor / Claude から使う（MCP 連携）

iknow.dev は MCP（Model Context Protocol） に対応しています。Cursor / Claude などの MCP クライアントから iknow.dev のナレッジを直接参照・編集できるため、ブラウザを開かずに IDE や AI チャット上で iknow.dev のナレッジを呼び出せます。

このページは MCP 連携の 入口から仕組みまで を 1 ページにまとめたものです。まず「MCP とは」「接続する」で使い始め、内部の仕組みを知りたいときは末尾の「技術リファレンス（仕組み）」を参照してください。

MCP とは（30秒で理解する）

MCP は、AI クライアント（Cursor / Claude など）が外部のデータソース（iknow.dev など）にツール越しにアクセスするための共通プロトコルです。iknow.dev では MCP サーバーが用意されているので、ユーザーは AI クライアントに 「iknow.dev に接続する」 設定をするだけで、対話の中で次のような操作ができます。

• 自分のエージェントのナレッジを検索する
• ナレッジ本文を取得する
• ナレッジを新規作成・追記・更新する（オーナーのみ）
• タイトル・タグ・関連ナレッジのリンクを更新する（オーナーのみ）
• 新規エージェントを作成する（認証ユーザー全員）
• セクションコメントを追加する（メンバー以上）

接続先の URL（3 モード）

接続先は 3 種類あり、用途に応じて選びます。スコープはナレッジ単位ではなく エージェント単位 です。

迷ったら /mcp（横断利用） がおすすめです。1 回登録するだけで、アクセスできる全エージェントを切り替えながら使えます。特定 1 エージェントに絞りたいときだけ /mcp/{agentCode} を使います。

Cursor からワンクリックで接続する

最も簡単な方法です。手動でコピーする必要はありません — 自動設定されます。

1. ブラウザで iknow.dev にログインし、ユーザーメニュー → アカウント設定を開きます。
2. 「エージェント連携」 セクションの 「Cursorへインストール」 ボタンを押します。
3. OAuth クライアントが自動発行され、ブラウザが Cursor を起動して、オーケストレーション MCP（/mcp）が mcp.json に 自動登録 されます（Client ID / Client Secret もディープリンク経由で Cursor 側に渡されます）。

ワンクリック登録が接続するのは、横断利用できるオーケストレーション /mcp です。特定 1 エージェントに絞りたい場合は手動接続で /mcp/{agentCode} を指定してください。

Claude から接続する（カスタムコネクタ）

Claude では、発行直後に表示される 3 項目を コピーしてカスタムコネクタに設定 します。

1. アカウント設定で 「Claudeへインストール」 を押します。
2. 発行直後に その場で一度だけ 表示される次の 3 項目を必ずコピー します（後から再表示不可）。
   • リモート MCP サーバー URL — https://{ドメイン}/mcp
   • OAuth Client ID
   • OAuth Client Secret
3. Claude の カスタムコネクタ（MCP コネクタ） 設定画面に、コピーした 3 項目を貼り付け、あわせて次も設定します。

4. Claude から初回接続すると iknow.dev の認可画面が開き、認可するとアクセストークンが発行されます。

⚠ Client Secret は発行直後の画面でのみ表示されます。Claude のカスタムコネクタ設定に貼り付ける前に、必ずコピーして保存してください。紛失した場合は古いクライアントを削除し、新規発行してください。

ナレッジの登録と管理（対話で操作する）

ブラウザのナレッジエディターを開かなくても、Cursor や Claude のチャットから 自然言語で指示するだけ で、自分がオーナーのエージェントのナレッジを登録・更新できます。AI が内部で MCP ツール（search-knowledge → get-knowledge → create-knowledge など）を呼び出すため、ユーザーがツール名を覚える必要はありません。

登録・更新の流れ（AI が実行する内部手順）

1. 対象エージェントを選ぶ — 横断接続（/mcp）の場合、get-reference name=agents でアクセス可能なエージェント一覧を確認し、agent_code を指定します。
2. 既存ナレッジを確認 — 新規作成前に search-knowledge で同テーマの既存ページがないか探します（あれば append-knowledge や update-knowledge の方が望ましい）。
3. 内容を書き込む — 形式に応じてツールを使い分けます（下表）。
4. 変更意図（intent） — すべての書き込み操作には 変更の意図（コミットメッセージ相当、最大 1000 文字）が必須です。AI が自動で付与し、ナレッジエディターの変更履歴に記録されます。

記法・詳細仕様

• 本文は Markdown または テーブル形式 JSON（配列の配列）です。HTML は使えません。
• ツールの引数や詳細な使い分けは get-reference name=mcp-tools-guide で取得できます。
• Markdown 記法・テーブル JSON の仕様は get-reference name=markdown-guide を参照してください。

できること（ツール一覧と権限）

利用ユーザーの権限によって使えるツールが切り替わります。

パブリックエージェントの参照系ツールは匿名でも使えますが、プライベートエージェントの参照にはメンバー以上が必要です。書き込みツールはすべて オーナー専用 で、権限がないと 403 になります。エージェント一覧で自分の役割を確認してください。

*create-agent は接続中エージェントの役割に依存せず、認証済みユーザー（メンバー・オーナー）なら誰でも実行できます（匿名 /mcp/public には非公開）。

Web 画面との使い分け

困ったとき

技術リファレンス（仕組み）

ここからは MCP サーバーの内部仕様です。通常の利用では読む必要はありません。iknow.dev の MCP サーバーは Laravel MCP（laravel/mcp v0）で実装しています。

3 つの接続モードの詳細

Orchestration — POST /mcp

Single Agent — POST /mcp/{agentCode}

Public Read-only — POST /mcp/public/{agentCode}

オーケストレーション利用フロー（/mcp）

1. OAuth 認可 — クライアントは /mcp を 1 回だけ登録・認可する
2. get-reference name=agents — アクセス可能なエージェント一覧を取得
3. LLM がエージェント選択 — LLM 自身が最適なエージェントを判断する（サーバーは自動選択しない）
4. agent_code を渡してツール実行 — search-knowledge / get-knowledge / create-knowledge などに agent_code を指定（横断接続では初回必須・同一セッション内で記憶され省略可）
5. 都度ロール認可 — agent_code から Agent を解決し owner / member を判定。許可外はエラー

get-reference name=agents agent_code=<code> の戻り値（JSON 例）:

{
  "agents": [{
    "name": "...",
    "code": "agent-code",
    "description": "...",
    "role": "owner|member|null",
    "allowed_tools": ["..."],
    "knowledge_count": 42,
    "top_tags": ["..."],
    "recent_titles": ["..."]
  }],
  "total_count": 1
}

認可レイヤーと実装

ツールはロール別の許可セットで認可します（IknowServer::$tools で公開ツールを定義）。

• リンクの作成・解除 — update-knowledge-meta の link_to / unlink_from で実施（無向・untyped・冪等）
• 削除 — delete-knowledge はオーナー専用のソフトデリート（REST DELETE /api/v1/knowledge/{id} と同一挙動）

OAuth 認証フロー

1. クライアント発行 — アカウント設定の「MCP OAuth」または「Cursor / Claude へインストール」ボタンで client_id / client_secret を作成
2. 認可コード取得 — GET /oauth/authorize でユーザーが認可。scope は mcp:use 固定
3. アクセストークン — POST /oauth/token で Bearer トークンを取得（Expert 単位に発行）
4. MCP に接続 — Authorization: Bearer <token> で /mcp または /mcp/{agentCode} を呼び出す

匿名アクセス: /mcp/public/{agentCode} は認証不要。プライベートエージェントには 404 を返します。