Cursorを自分用に拡張する：MCPの追加と認証、Skills、Subagents、Hooksの作り方と、承認・権限との関係を、公式ドキュメントで確かめる

この記事は公式ドキュメントを2026年10月24日に読んでまとめたもので、実際に使って確かめた記録ではありません。運営者はCursorを入れていますが、使い心地はこの記事には書いていません。設定の書き方、コマンド、メニュー名は公式に書かれたとおりに写しており、動作確認はしていません。公式の文章は要約の形で取得したため、長いコード例を一字一句そのまま取れなかったものがあります。その場合は、公式が示したキーと値を僕らがJSONなどの形に直したもの、と明記しています。引用は短く、ほとんどを言い換えています。

先に結論

• つなぐのはMCP。 最短は、Customizeの「MCPs」から「Add to Cursor」を押す方法です。自分で書くなら、ローカルのサーバーは command と args、リモートのサーバーは url と、必要なら headers か auth を書きます。設定を書き換えたあとは、Cursorの再起動が要る、とヘルプに書かれています。
• 手順書はSkills、分担はSubagents。 Skillsは SKILL.md に name と description を書くだけで始められます。Subagentsは、.cursor/agents/ にMarkdownを置きます。Subagentsは、親の会話を見ない、きれいな状態から始まります。
• 止めたいならHooks。 beforeShellExecution、beforeMCPExecution、preToolUse などで、実行前に判定できます。ただし、初期設定は「失敗したら通す」です。
• 承認との関係は層になっている。 MCPのdocsは、初期設定ではツールを使う前に承認を求める、と書いています。ただしヘルプによると、Cursor 3.6以降の既定のRun ModeはAuto-reviewで、許可リストのMCPツールは即実行、それ以外は分類器が判定します（人の承認の画面が出ないことがあります）。承認を減らす仕組み（許可リスト）も、制限する仕組み（Hooks、チームの管理）もあり、公式は許可リストを「セキュリティの保証ではない」と書いています。
• 読めていないところ。 Hooksと承認チェックの前後関係、Subagentsの承認の引き継ぎ、Skillsのスクリプト実行の承認は、読んだ範囲で書かれていませんでした。書かれていないものを、この記事は書いていません。

前提：用語をそろえる

• mcp.json：MCPサーバーの設定ファイルです。最上位のキーは mcpServers です。
• stdio / Streamable HTTP / SSE：MCPのつなぎ方です。stdioは手元でプログラムを起動し、後ろ2つはURLに話しかけます。
• Skill：SKILL.md を中心にしたフォルダで、エージェントが関連すると判断したときに読み込む手順書です。
• Subagent：親のエージェントが仕事を任せる、自分の文脈の窓を持った助手です。
• Hook：エージェントの流れの決まった時点で、あなたのスクリプトを呼ぶ仕組みです。標準入力にJSONを受け取り、標準出力にJSONを返します。
• fail-open / failClosed：Hookが失敗したとき、処理を通す動きと、止める設定です。
• Run Modes / 許可リスト：承認を減らす仕組みです。前のガイド（02）に詳しく書きました。

たとえるなら、MCPは外の工具屋さんとの電話線、Skillsは棚の手順書、Subagentsは任せる助手、Hooksはドアの警備員です（僕らのたとえで、公式の表現ではありません）。

MCPを追加する：3つの入り口

公式が書いている入り口は次のとおりです。

そのほか、Cursor Marketplaceの公式のPlugin、コミュニティのcursor.directory、チーム管理者が配るチームのマーケットプレイス、拡張機能向けのAPI（vscode.cursor.mcp.registerServer()）も書かれています。

設定ファイルの置き場所と、同じ名前が重なったとき

プロジェクトの .cursor/mcp.json は、チームで共有する道具向けで、gitに入れる想定です。~/.cursor/mcp.json は自分の全プロジェクト向けです。ヘルプは、2つのファイルは合わされ、同じサーバー名があればプロジェクト側が優先される、と書いています。一方、MCPのdocsの本体のページには、重なったときの優先順位が書かれていませんでした。CLIのMCPページには「プロジェクト、全体、入れ子」の順という記載があります。ページによって書き方がそろっていないので、同じ名前を2か所に置くのは避けるのが無難です（これは僕らの見立てです）。

ローカルのサーバー（stdio）

ヘルプにある例に近い形です（動作確認はしていません。API_KEY の値の文字列は読み切れていないので、僕らが置いた仮のものです）。

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "mcp-server"],
      "env": {
        "API_KEY": "your-key-here"
      }
    }
  }
}

MCPのdocsは、stdioの項目を表にしています。type（必須で "stdio"。ただし公式の例は type を省いています）、command（必須。システムのパスにあるか、フルパスで書く。例は npx、node、python、docker）、args、env、envFile（.env や ${workspaceFolder}/.env のように書く）です。envFile はstdio専用で、リモートのサーバーでは使えません。リモートでは、シェルやシステムの環境変数を、後述の ${env:NAME} で参照します。

ヘルプは、シェルの設定ファイルで定義した環境変数にサーバーが依存する場合は、Cursorからそれが見えるようにして、設定を直したらCursorを再起動するよう書いています。

リモートのサーバー（URL）

公式のdocsの例は、次の形です。

{
  "mcpServers": {
    "server-name": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "API_KEY": "value"
      }
    }
  }
}

変数の展開：秘密を直書きしない

MCPのdocsによると、command、args、env、url、headers の中で、次の書き方が展開されます。

公式の例は、headers に "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}" と書く形です。公式は、資格情報は直書きではなく環境変数で渡すよう勧めています。ヘルプのページには、鍵の扱いについての注意は読んだ範囲で見つかりませんでした（プロジェクトの .cursor/mcp.json は、gitにコミットしてチームで共有する、とは書かれています）。注意書きはMCPのdocsの側にあり、秘密は環境変数で渡して直書きしないこと、APIキーの権限は最小にすること、と書かれています。共有するファイルに鍵を直書きしない、が基本です。

認証：3つのやり方

固定のOAuth設定

公式の例は次のとおりです（動作確認はしていません）。

{
  "mcpServers": {
    "oauth-server": {
      "url": "https://api.example.com/mcp",
      "auth": {
        "CLIENT_ID": "your-oauth-client-id",
        "CLIENT_SECRET": "your-client-secret",
        "scopes": ["read", "write"]
      }
    }
  }
}

公式の補足を拾います。

• 公式が例に挙げた「固定が要る」提供元は、FigmaとLinearです。
• リダイレクトURLは、Webとクラウドのエージェント用が https://www.cursor.com/agents/mcp/oauth/callback、デスクトップアプリ用が http://localhost:8787/callback です。両方から認証する人がいるなら、両方を登録します。どのサーバーかは、OAuthの state で見分けられると書かれています。
• 動的登録のとき、デスクトップアプリは2つのURLを両方登録します。デスクトップのURLだけにしたいなら、固定の CLIENT_ID を指定します。
• scopes を省くと、Cursorは /.well-known/oauth-authorization-server から scopes_supported を探します。更新用のトークン（refresh token）に offline_access のようなスコープが要るサーバーでは、auth.scopes に足す、とあります。
• auth の値にも ${env:MCP_CLIENT_ID} のような展開が使えます。
• 認証の方式は、PKCE付きの認可コードフローで、保護リソースのメタデータ（RFC 9728）とリソース指示子（RFC 8707）を使う、と書かれています。動的登録では、秘密のない公開クライアントとして登録します。期限が切れたトークンは更新用トークンで更新され、無ければ再ログインです。

Cloud Agentsでの認証は別物

MCPのdocsは、Cloud Agentsのサインインはローカルとは別で、ローカルでサインアウトしてもCloud Agentsは出ない、と書いています。Cloud AgentsのCapabilitiesのページには、次のことが書かれています。

• MCPは、cursor.com/agents のMCPのドロップダウンで自分のサーバーを足すか、管理者がDashboardの「Plugins & MCPs」で配ります。リポジトリの中の mcp.json については、そのページには書かれていませんでした。
• つなぎ方は、HTTPとstdioが使えます。SSEと mcp-remote は使えません（公式は警告の印をつけています）。
• HTTPは、サーバー設定がVMの中に入らず、エージェントは更新用トークンやヘッダーを見られず、呼び出しはバックエンド経由になるので、推奨と書かれています。stdioはVMの中で動くため、エージェントが設定や環境変数に触れられる、と書かれています。
• OAuthは利用者ごとの認可で、チームで共有するサーバーでも同じです。MCPの設定は保存時に暗号化され、env、headers、CLIENT_SECRET は保存後に隠され、誰にも読み戻せません。変えるときの手順は、読んだ範囲では書かれていませんでした。

MCPを足したあとの確認と運用

• ログ。 出力パネル（Cmd/Ctrl+Shift+U）で「MCP Logs」を選びます。初期化、ツールの呼び出し、エラーが出ます。docsは、ショートカットの表記が2つのキーがつながって見える形で書かれているので、画面で確かめてください。
• ツールごとのオン・オフ。 チャット欄の上のツール一覧で、ツール名を押すと切り替えられます（ヘルプ）。
• サーバーの無効化。 Customizeの「MCPs」のトグルです。無効にしたサーバーは読み込まれず、チャットにも出ません。
• やり直し。 一度消して、入れ直します。npmで入れたサーバーを更新するときは、Customizeから消し、npm cache clean --force を実行して、入れ直す、と公式にあります。
• 失敗の影響。 1つのサーバーが失敗しても、ほかのサーバーには影響しないよう分けられる、と書かれています。
• MCP Apps。 ツールが対話的な画面を返せる拡張に対応しています。表示できない場合も、普通のMCPの応答は返ります。プロトコルとして、Tools、Prompts、Resources、Roots、Elicitationも対応と書かれています。
• ツールの数の上限。 読んだ範囲では、どちらのページにも書かれていませんでした。変更履歴の2.4には、MCPの定義とツールが .cursor のJSONファイルになり、エージェントが「必要なときだけ」読み込むので、トークンの使用を減らせる、と書かれています。
• 機微なデータを扱うとき。 MCPのdocsの注意は4つです。信頼できる開発者とリポジトリのサーバーだけを入れる、サーバーが触るデータとAPIを確かめる、APIキーは最小の権限に絞る、重要な連携ではサーバーのソースを見直す。FAQには、機微なサーバーは stdio でローカルで動かす、とあります。

CLIから

CLIのMCPのページに、次のコマンドがあります。

agent mcp list
agent mcp list-tools playwright
agent mcp login <名前>
agent mcp enable <名前>
agent mcp disable <名前>
agent --approve-mcps "query my database for recent errors"

エディタと同じMCPの設定を使います。agent mcp enable はそのサーバーを手元の承認済みリストに足し、--approve-mcps はその実行のあいだ、すべてのMCPサーバーの承認を飛ばします。後者は、承認の確認を全面的にやめることになるので、信頼できるサーバーだけの環境で使うことを僕らは勧めたいです（見立てです）。

Skillsを作る

最小の形

Skillは、SKILL.md を含むフォルダです。公式の例の冒頭は次のとおりです（文面を短くして写しています）。

---
name: my-skill
description: Short description of what this skill does and when to use it.
---

# My Skill

Detailed instructions for the agent.

## When to Use
- Use this skill when...

## Instructions
- Step-by-step guidance for the agent

置き場所は次のとおりです。

フォルダの名前が、そのSkillの名前になります。サブフォルダでまとめることもでき、リポジトリの中のどこかにある .cursor/skills/ や .agents/skills/ も拾われ、入れ子のプロジェクトにあるものは、そのフォルダの範囲に限られます。Cursorは起動時にSkillを見つけ、どれを使うかはエージェントが文脈で判断します。

フロントマターの項目

license や compatibility は、このページには書かれていませんでした。paths の具体的な例の文字列は、読んだ範囲では確認できていません。

呼び方

• 自動：エージェントが関連すると判断したとき。
• 手動：Agentのチャットで / を入れ、名前を探す。そのメッセージだけに付く。
• セッション全体：Custom Modeとして使う（Macは Option+Enter、Windowsは Alt+Enter）。
• 一覧：Customizeの「Skills」。

スクリプトを同梱する

scripts/（実行できるコード）、references/（必要なときに読む資料）、assets/（雛形や画像）を置けます。SKILL.md からは、スキルのルートからの相対パスで参照します。SKILL.md に、同梱のスクリプトを実行させる手順を書く形です（例の文字列は読み切れていません）。言語は問わず、スクリプトは自己完結で、親切なエラーメッセージを出し、端の場合も扱うよう書かれています。スクリプトの実行に承認や隔離がどう関わるかは、このページには書かれていませんでした。 前のガイド（04）でも同じ点を書きました。

作る近道と、取り込み

• 組み込みのSkillに、/create-skill、/create-rule、/create-hook、/create-subagent、/migrate-to-skills、/review、/loop など19個があります。/create-skill が何をするかの説明は、読んだ範囲では確認できていません。/create-hook と /create-subagent が何をするかは、Skillsのdocsには一覧に名前があるだけで、Customizeのdocsにも説明はありませんでした。
• /migrate-to-skills（Cursor 2.4）は、条件に合う「動的なRules」と、スラッシュコマンドをSkillに変えます。alwaysApply: true や globs を持つRules、ユーザーのRulesは移行されません。出力は .cursor/skills/ に置かれ、見直せます。
• GitHubのリポジトリからは、Customizeの「From GitHub Repository」で取り込めます。リポジトリに .cursor-plugin/marketplace.json が要る、と書かれています。

Cloud Agentsとの関係

同期されるのは ~/.cursor/skills/ だけです。設定の「Settings → Agents」で「Sync Skills for Cloud Agents」をオンにします。同期されたSkillは自分専用で、チームには共有されません。自分で起動したCloud Agentには読み込まれますが、Automationsの実行には読み込まれないので、Automationsで使うならリポジトリの .cursor/skills/ に入れます。自己ホストのワーカーも、同期されないものは使えず、リポジトリのSkillか、ワーカーのイメージに焼き込みます。チーム管理者は、Team Settingsの「Security & Identity」で同期を止められます。

Subagentsを作る

最小の形

カスタムのSubagentは、YAMLのフロントマター付きのMarkdownです。公式の例（security-auditor）の冒頭は次のとおりです。

---
name: security-auditor
description: Security specialist. Use when implementing auth, payments, or handling sensitive data.
model: inherit
readonly: true
---

You are a security expert auditing code for vulnerabilities.

When invoked:
1. Identify security-sensitive code paths

置き場所は、プロジェクトが .cursor/agents/、ユーザーが ~/.cursor/agents/ で、互換用に .claude/agents/ と .codex/agents/ も読まれます。プロジェクトのものが、同名のユーザーのものより優先され、同じ名前が複数の場所にあれば .cursor/ が .claude/ と .codex/ に勝つ、と書かれています。

model には、角括弧でオプションを付けられます。公式の例は、composer-2.5[fast=false]、claude-opus-5[effort=high]、claude-opus-5[context=300k] などです。使えるオプションはモデルによって違い、管理者がそのモデルを禁止している場合、プランに含まれない場合、旧プランでMax Modeが無い場合は、互換のあるモデルに切り替わる、と書かれています。

呼び方と動き方

• 自動：エージェントが、タスク、description、使えるツールを見て任せます。説明に「use proactively」のような文を入れると、任せやすくなる、と書かれています。
• 明示：プロンプトに /verifier のように書くか、自然な文で名前を挙げます。
• 前面と背面：前面は終わるまで待ち、背面はすぐ返って並行して働きます。背面の出力は ~/.cursor/subagents/ に書かれ、親が読めます。
• きれいな文脈から始まる。 Subagentは、それまでの会話を見ません。親が、必要な情報をプロンプトに入れる必要があります。
• 再開。 実行ごとにエージェントのIDが返り、渡し直すと文脈ごと再開できます。
• 入れ子。 Cursor 2.5から可能ですが、1段までです。入れ子にはTaskツールが要り、Hooksやツールの方針で止められる、と書かれています。
• MCPツール。 ローカルのSubagentは、親のツール（MCPを含む）を引き継ぎます。クラウドのSubagentは、cursor.com/agents で設定したチームのMCPサーバーを使います。

並列にするときの落とし穴

初期設定では、Subagentは親と同じチェックアウトを共有し、同時の編集が互いを上書きしうる、と公式が書いています。分けたいときは、分けるよう頼みます（公式の例は「それぞれ別の環境で動かして」という頼み方です）。すると、各自が自分のブランチを持ち、同じマシンの隔離されたGitのワークツリーか、リポジトリを複製したクラウドVMで動きます。変更は、親がマージするまで各ブランチに残ります。

費用

それぞれが独立してトークンを使うので、5つ並べると約5倍、と公式にあります。速くなるわけではなく、利点は文脈の隔離だと書かれています。名前を指定した他社モデルは、親がAutoやComposerでも、他社モデルの使用として数えられます。TeamsとEnterpriseでは、対象の他社モデルにCursor Token Rateもかかります。料金は前のガイド03に書きました。

公式が書いている作り方の目安

• 責任が1つに絞られたものを書く。最初は2〜3個。
• description が任せる判断の中心なので、具体的に。「汎用のタスクに使う」のような曖昧な説明は避ける。
• プロンプトは短く。.cursor/agents/ はバージョン管理に入れる。
• 僕らの補足です。文脈の隔離が要らない単発の作業には、Skillのほうが向くと思います（見立て）。

Subagentsと承認：書かれていないこと

Subagentsのdocsは、承認の流れを説明していません。readonly が書き込みを制限すること、Hooksやツールの方針が起動を止められることが書かれているだけです。Run Modesのdocsにも、Subagentsが親のモードや許可リストを引き継ぐのかは書かれていませんでした。変更履歴の2.5には、Subagentの許可の依頼の流れを改善した、とあります。細かいことは、読んだ範囲では分かりません。

Hooksを作る

最小の形

手順は、公式のクイックスタートにあります。

1. <プロジェクト>/.cursor/hooks.json（プロジェクト）か ~/.cursor/hooks.json（ユーザー）を作る。
2. "version": 1 を書き、イベント名に { "command": ... } の配列を対応させる。
3. スクリプトを書いて、chmod +x で実行できるようにする。
4. 保存すれば再読み込みされる。それでも読み込まれなければ、Cursorを再起動する。

公式の最初の例は、ユーザー用の hooks.json で、afterFileEdit に ./hooks/format.sh を1つ置くものです。次は、その中身（キーと値）を、僕らがJSONの形に直したものです。

{
  "version": 1,
  "hooks": {
    "afterFileEdit": [
      { "command": "./hooks/format.sh" }
    ]
  }
}

公式の format.sh は、標準入力を読んで捨て、終了コード0で終わる形です。コメントに「読んで、何かして、0で終わる」と書かれています。

設定の項目

絞り込みと時間切れの公式の例は、beforeShellExecution に ./scripts/approve-network.sh を置き、timeout を30、matcher を curl|wget|nc にするものです。

{
  "version": 1,
  "hooks": {
    "beforeShellExecution": [
      {
        "command": "./scripts/approve-network.sh",
        "timeout": 30,
        "matcher": "curl|wget|nc"
      }
    ]
  }
}

"type": "prompt" では、command の代わりに prompt を書き、LLMが { ok, reason? } を返します。速いモデルが既定で、model で変えられ、$ARGUMENTS が入力のJSONに置き換わります。公式の例は「このコマンドは安全か。読み取りだけ許可」と問う内容で、timeout は10です。Cloud Agentsでは使えません。

どこに置くか、どれが勝つか

優先は、Enterprise、Team、Project、Userの順で、Pluginはそのあとです。一致したフックは、どの層のものも全部動きます。 権限の返事は、deny が ask に勝ち、ask が allow に勝ちます。user_message と agent_message はつなげられ、followup_message のようなほかの項目は、最後の返事が勝ちます。同じ層、同じイベントの複数の項目の実行順は、読んだ範囲では書かれていませんでした。

主なイベントと、入出力

イベントは、エージェント用（sessionStart、sessionEnd、preToolUse、postToolUse、postToolUseFailure、subagentStart、subagentStop、beforeShellExecution、afterShellExecution、beforeMCPExecution、afterMCPExecution、beforeReadFile、afterFileEdit、beforeSubmitPrompt、preCompact、stop、afterAgentResponse、afterAgentThought）、Tab用（beforeTabFileRead、afterTabFileEdit）、アプリの起動時用（workspaceOpen）に分かれます。Tab用のフックは、Tabの補完だけで動き、Agentでは動きません。workspaceOpen は、公式がデスクトップアプリとCLIで動くと書いているフックです。そのほかのフックをagent CLIで動かせるかは、Hooksのページだけでは確認できていません。変更履歴の2.4には、CLIにチームとMDMのフックを足した、CLIでClaude Codeのフックと互換にした、という記載があります。

すべてのフックの入力には、conversation_id、generation_id、model（旧式のモデル名と説明されている）、model_id、hook_event_name、cursor_version、workspace_roots、user_email、transcript_path などが入ります。

matcher が何と照らし合わされるかは、イベントごとに違います。preToolUse などはツールの種類（Shell、Read、Write、Grep、Delete、Task、MCP:<ツール名>）、beforeShellExecution などはコマンド全文、subagentStart などはサブエージェントの種類です。beforeMCPExecution は、その表に載っていませんでした。公式は、MCPでは、スクリプトの中で mcp_server_name と tool_name で見分けるよう書いています。

終了コードと、「通してしまう」初期設定

つまり、スクリプトが落ちた、時間切れになった、というだけでは、止めたかった操作が通ります。公式は、安全が重要なフックには failClosed: true を使うよう書いており、beforeMCPExecution では特に勧めています。さらに、beforeMCPExecution では、command ではなく mcp_server_name と tool_name で判定し、サーバー名が空だったり想定外だったりしたら拒否する形を勧めています。起動の文字列は、環境ごとに違うからです。

動かせるもの

環境変数として、CURSOR_PROJECT_DIR（ワークスペースのルート）、CURSOR_VERSION、CURSOR_USER_EMAIL（ログイン時）、CURSOR_TRANSCRIPT_PATH（会話の記録が有効なとき）、CURSOR_CODE_REMOTE（リモートのワークスペースで "true"）、CURSOR_PLUGIN_ROOT（プラグインのフックだけ）、Claude互換の CLAUDE_PROJECT_DIR が使えます。sessionStart の出力の env に入れた値は、そのセッションの以降のフックに渡ります。

Windowsでは、デスクトップアプリが入力のJSONをPowerShell経由で渡す、と書かれています。

自分で組んだ例：危険なコマンドを止める

次の例は、公式の例ではなく、僕らが、上に書いた入出力のルールだけから組んだ形です。jq がある前提で、動かしていません。beforeShellExecution が受け取るJSONの command を調べ、ある単語を含んだら、permission を deny にして返します。

#!/bin/bash
# 標準入力のJSONから、実行しようとするコマンドを取り出す
cmd=$(jq -r '.command // empty')
if echo "$cmd" | grep -qE 'rm -rf|git push --force'; then
  echo '{"permission":"deny","user_message":"このコマンドは止めました","agent_message":"破壊的なコマンドは禁止されています"}'
  exit 0
fi
echo '{"permission":"allow"}'
exit 0

設定側は、beforeShellExecution にこのスクリプトを置き、failClosed: true を足します。公式の説明に沿えば、jq が無くてスクリプトが失敗したときも、処理は止まります。逆に failClosed を付けないと、失敗したときに素通しになります。こうした単語の一致は、迂回が簡単なので、これだけで安全にはなりません（僕らの見立てです）。

落とし穴が2つあります。1つ目、failClosed: true では空の出力が止める側に倒れるので、通すときも何かのJSONを返す必要があります。2つ目、この例は対象外のコマンドに allow を返しますが、allow がユーザーの承認の画面まで飛ばすのかは、公式は読んだ範囲で書いていません。迷うなら、allow の代わりに ask を返す形も選べます（permission の値に ask があることは公式に書かれています）。

修正を繰り返す stop の使い方

stop が空でない followup_message を返すと、それが次の発言として自動で送られ、「終わるまで直す」流れが作れます。loop_count は0から数え、loop_limit の既定は5です。null にすると上限が無くなるので、費用が膨らみうる点に注意が要ります（僕らの見立てです）。

Cloud Agentsでの違い

• 動くのはコマンド型のフックだけで、.cursor/hooks.json の内容と、Enterpriseではチームとエンタープライズのフックが読まれます。
• sessionStart、sessionEnd、beforeMCPExecution、afterMCPExecution、beforeTabFileRead、afterTabFileEdit、workspaceOpen は使えません。type: "prompt" も使えません。
• ユーザー用の ~/.cursor/hooks.json は読まれません。
• HTTPのMCPツールは preToolUse と postToolUse に MCP:<ツール名> として現れますが、updated_input は無視され、ツールの出力は隠されます。
• 最初の読み取りだけのターンのあいだは、フックは動きません。
• 自己ホストのワーカーは、プロジェクトのフックを動かし、Enterpriseならチームとエンタープライズのフックも動かします。

配り方

プロジェクトのフックは、コミットすれば、信頼されたワークスペースでチームに届きます。MDMは、組織が上の場所にファイルを置く方式で、Cursorは配りません。クラウド配布（Enterprise）は、ダッシュボードで設定し、約30分ごとに同期されます。ダッシュボードのフックは、failClosed と matcher が使えず、1つのフックが1つのスクリプトか1つのプロンプトです。「Block until hooks are ready」を入れると、フックの準備ができるまで最初の発言を待ちます。

動かないとき

公式の案内は、CustomizeのHooksのタブと、出力パネルのHooksのチャンネルで、設定、実行、エラーを見ることです。設定は保存で再読み込みされ、それでもだめなら再起動です。相対パスが、フックの置き場所（プロジェクトかユーザーか）に合っているかも確かめます。

うまくいかないときの早見表

各所に散っている公式の記載を、僕らが1つの表にまとめたものです。

承認と権限の関係：層で考える

前のガイド（02）で、Run Modes、許可リスト、サンドボックスを書きました。拡張を作るときに関わる層を、公式の記載から並べます。

permissions.json の公式の例は次のとおりです。

{
  "mcpAllowlist": [
    "github:*",
    "linear:list_issues"
  ]
}

書き方の公式の説明は、サーバー:ツール、大文字小文字は区別せず、* が使え、コロンの無い項目は無視される、というものです。*:* は「すべて」で、CLIでも Mcp(*:*) は「注意して使う」と書かれています。置き場所は、~/.cursor/permissions.json（全体）と <ワークスペース>/.cursor/permissions.json（リポジトリ。コミットが勧められている）で、配列は連結されます。優先は、チームのダッシュボード、permissions.json、IDEの設定の許可リストの順です。キーがあるのに連結後の配列が空なら、許可リストは空になり、IDEの許可リストには戻りません。公式は、許可リストと autoRun の指示は「ベストエフォートの利便性」で、セキュリティの保証ではない、と書いています。

Hooksと承認の前後関係。 Run Modesのdocsは、Hooksが承認の判定の前に動くのか後に動くのか、承認をすり抜けられるのか、を書いていません。Hooksのdocsは、同じイベントに対する権限の返事のあいだでは deny が ask と allow に勝つと書いていますが、承認の画面との関係は書いていません。前のClaude Codeのガイド（06）に書いたように、Claude Code側は明確に書かれていましたが、Cursorについては、読んだ範囲で確かな答えがありません。自分の環境で、小さなフックと小さな許可リストで挙動を確かめてから信頼する、というのが現実的です（僕らの見立てです）。

Hooksを使う前の信頼。 プロジェクトのフックは「信頼されたワークスペースだけで動く」と書かれています。ところが、前のガイド（02）に書いたとおり、Workspace Trustの機能は既定で無効と書かれています。無効のとき、この「信頼」がどう扱われるのかは、読んだ範囲では書かれていませんでした。他人のリポジトリを開くときは、.cursor/hooks.json と .cursor/mcp.json の中身を先に読む、という習慣が安全です（僕らの見立てです）。

プラグインにまとめる

MCP、Skills、Subagents、Hooks、Rules、Commandsは、Pluginとしてまとめて配れます。公式のdocsにある構成は、plugin.json、skills/、mcp.json を持つフォルダです。Cursor独自の形式は .cursor-plugin/plugin.json で、Rulesやエージェント、コマンド、Hooksも含められます。プラグインの mcp.json では、${CURSOR_PLUGIN_ROOT} でプラグインのルートを指せます（${PLUGIN_ROOT} は展開されません）。試すときは ~/.cursor/plugins/local/my-plugin に置き、再起動か「Developer: Reload Window」を実行し、Customizeで確かめます。

公式のマーケットプレイスについては、ヘルプのMarketplace securityに、掲載前の手動の審査、更新ごとの審査、ソース公開の必須、自動更新はしないこと、危険が分かれば素早く取り下げることが書かれています。同時に、プラグインはサードパーティのソフトで、入れるのは自分の判断と責任、とも書いています。ソースを読み、含まれるMCPサーバーが許可リストに合うか確かめるよう勧めています。ブロックされたMCPサーバーを含むプラグインは、入るけれども、そのサーバーは呼び出せません。MCPのサーバー、Skills、Hooksそれぞれの別の審査の手順は、そのページには書かれていませんでした。Enterpriseでは、ローカルのプラグインの取り込みは既定で無効で、管理者が許可します。

最初の10分でやること

公式に書かれている範囲で、小さく始める順番です。

1. MCPを1つだけ入れる。 読み取りだけの、出どころの確かなサーバーを選びます。Customizeの「MCPs」から「Add to Cursor」を押すか、.cursor/mcp.json に書いて、Cursorを再起動します。
2. 承認の画面を一度見る。 エージェントにそのMCPを使わせ、ツール名の矢印で、渡される引数を確かめます。出力パネルの「MCP Logs」も開いておきます。既定のAuto-reviewでは画面が出ないことがあります。見たいときは、Run Modeを、空の許可リストのAllowlistにします（前のガイド02に書きました）。
3. 許可リストはまだ足さない。 動きを理解してから、permissions.json の mcpAllowlist に、必要なツールだけを書きます。
4. 最小のフックを置く。 ~/.cursor/hooks.json に、公式のクイックスタートと同じ、何もしない afterFileEdit のフックを置き、chmod +x して、CustomizeのHooksのタブに出るかを見ます。
5. Skillを1つ書く。 .cursor/skills/my-skill/SKILL.md に、name、description、数行の指示を書き、チャットで / から呼べるか見ます。
6. Subagentを1つ書く。 .cursor/agents/verifier.md のような、readonly: true の確認役を1つだけ作り、/verifier で呼びます。

以降は、僕らの整理です。最初に作る拡張は、失敗しても困らない、読み取り中心のものにします。止める系のフックは、スクリプトを単体で試してから入れ、failClosed の有無で挙動がどう変わるかを、危険の無い操作で確かめます。

僕らの見立て：どれを選ぶか

ここからは僕らの見立てで、公式の推奨そのものではありません。

気をつけること

• この記事は、実際に使って確かめた記録ではありません。運営者はCursorを入れていますが、使い心地はこの記事には書いていません。公式ドキュメントを読んで、キー、コマンド、メニュー名を写しただけです。長いコード例のうち、Hooksの各例とSubagentの例は、公式の要約から、キーと値を僕らがJSONなどの形に直したものです。実際の公式の例と、空白や並びが違うことがあります。
• 取得したのは、ページの要約です。Hooksのページは約12万4千字あり、前半と後半を分けて取りましたが、どちらも要約で、細かい例のコードは読み切れていません。kube_guard.py や track-stop.ts などの例のスクリプトは、コードが示されていないため書いていません。
• 日々更新される機能です。Cursor 3.6、3.5、2.4（2026年1月22日公開）、2.5（2026年2月17日公開）などの版の記載は、公式のページと変更履歴にあったものです。名前や挙動は変わります。
• 読んだ範囲では、MCP、Skills、Subagents、Hooksのどのページにも、ベータや実験的という表示はありませんでした。
• MCPの設定ファイルが重なったときの優先順位は、ページによって書き方が違います。前のガイド（04）はこの点に触れていなかったので、今回補いました。
• Windowsでは、管理者が「MCP Network Controls」を有効にし、コマンド型のサーバーに該当する設定があると、サンドボックスがWindows非対応のため、サーバーが起動しません。管理者が「No sandbox」の項目を足す必要がある、とヘルプにあります。
• MCPのインストール用リンクは、リンクを開くとCursorがインストールを促す形です。そのページには、リンクを信頼してよいかについての注意は書かれていませんでした。別のページ（Deeplinks）は、プロンプトなどのリンクを共有する前に、鍵などの機密情報が入っていないか見直すよう書いています。知らない人から来たリンクは、開く前に中身を見るのが無難です（見立てです）。
• 変更履歴の2.4に、SkillsとRulesのファイルの編集は、サンドボックスの中で承認が要らなくなった、と書かれています。承認が要らないことの影響をどう考えるかは、公式に書かれていません。
• 会社のパソコンでは、管理者の設定（チームのダッシュボード、MDM）が、この記事に書いた個人の設定より優先されることがあります。
• この記事は、セキュリティや法律の助言ではありません。

出典

• Model Context Protocol（MCP）（Cursor Docs、Cursor、2026-10-24確認）
• MCP Install Links（Cursor Docs、Cursor、2026-10-24確認）
• MCP integrations（Cursor Help、Cursor、2026-10-24確認）
• MCP（Cursor CLI、Cursor Docs、Cursor、2026-10-24確認）
• Agent Skills（Cursor Docs、Cursor、2026-10-24確認）
• Subagents（Cursor Docs、Cursor、2026-10-24確認）
• Hooks（Cursor Docs、Cursor、2026-10-24確認）
• Plugins（Cursor Docs、Cursor、2026-10-24確認）
• Customize Cursor（Cursor Docs、Cursor、2026-10-24確認）
• Cloud Agents Capabilities（Cursor Docs、Cursor、2026-10-24確認）
• permissions.json Reference（Cursor Docs、Cursor、2026-10-24確認）
• CLI Permissions（Cursor Docs、Cursor、2026-10-24確認）
• Run Modes（Cursor Docs、Cursor、2026-10-24確認）
• Deeplinks（Cursor Docs、Cursor、2026-10-24確認）
• Marketplace security（Cursor Help、Cursor、2026-10-24確認）
• Subagents, Skills, and Image Generation（Cursor Changelog、2026-01-22、2026-10-24確認）
• Plugins, Sandbox Access Controls, and Async Subagents（Cursor Changelog、2026-02-17、2026-10-24確認）