n8n-extending-mcp-official

n8n MCP の拡張

MCP アクセスが有効になっている n8n ワークフローは、コーディングエージェントが名前を指定して呼び出せるツールになります。一般的なケースは 2 つあります。

1. MCP が公開していない n8n の機能をラップする。 MCP では、ワークフローの CRUD、検証、実行、データテーブル、認証情報の一覧表示、実行の検索、フォルダーの作成／名前変更／移動、フォルダーとプロジェクトの一覧表示、タグの一覧表示と追加／削除に対応しています。まだ対応していないものは、フォルダーの削除、プロジェクトの作成／名前変更、タグの名前変更／削除、インスタンスのメタデータ、認証情報の作成です。n8n API を呼び出して結果をエージェントツールとして公開するワークフローを作成します。
2. 汎用ワークフローをツールとして公開する。 n8n 自体とは関係のないワークフロー（サードパーティ API の呼び出し、社内ビジネスロジックの実行、プライベートシステムでの情報検索など）も、MCP 経由で呼び出せるようにできます。コーディングセッション中にエージェントが実際の操作を実行できるようになります。

MCP はネイティブツールと同じようにワークフローを呼び出します。入力は Execute Workflow Trigger から、出力はワークフローの最後のノードから取得します。

どのような場合に利用するか

ケース 1（n8n の機能をラップする場合）：

• フォルダーの削除とプロジェクトの作成／名前変更：MCP ツールはありません。フォルダーの作成／名前変更／移動と、ワークフローのフォルダー間の移動には、登録済みのインスタンスで MCP ツール（create_folder、update_folder、move_workflows_to_folder）を利用できますが、削除には引き続き REST API が必要です。
• タグの名前変更／削除：MCP ではタグの一覧表示（list_workflow_tags）と追加／削除（update_workflow の addTags／removeTags。不明な名前は自動作成）に対応していますが、タグエンティティの名前変更や削除はできません。これらには REST API を利用できます。
• インスタンスのメタデータ（制限、プラン情報、設定済みインテグレーション）：MCP ツールはありません。
• 認証情報の作成：REST API（POST /credentials）はありますが、MCP ツールはまだありません。
• MCP がネイティブに公開していない n8n API 操作全般。

ケース 2（汎用エージェントツール）：

• 繰り返し発生するエージェントのタスクで、毎回説明するよりコード化しておきたいもの（検索、フォーマット、送信など）。
• エージェントが直接アクセスできないシステムに対する操作（プライベート API、社内サービス、サードパーティ連携など）。
• 今後のセッションで、実装方法を再度導き出すことなく呼び出せるようにしたい操作。

次のような場合は利用しないでください。

• 一度限りの質問。ユーザーに直接尋ねてください。
• MCP がすでにネイティブに公開している機能。

必ず守ること

1. 作成する前にユーザーに確認してください。 これはユーザーのインスタンスに認証情報を含むワークフローを作成します。明示的な承認を得る必要があります。
2. 認証情報は認証情報として設定し、テキストフィールドには入力しないでください。 n8n のほかの箇所と同じルールです。n8n-credentials-and-security-official を参照してください。

手順

• まず既存のラッパーを検索してください。 search_workflows({ tags: ['tool'] }) と、機能に関するキーワード検索を実行します。一致するものがあれば、重複して作成せず、それを使用してください。
• ケース 1 では、ステートレスでクエリ可能なユーティリティとして作成してください。 入力を受け取り、n8n の API を呼び出して結果を返します。副作用はありません。ケース 2 では副作用（送信、書き込みなど）が正当な場合もあります。その場合は、ツールの説明に明記してください。
• エージェントのコンテキストファイルを編集することも申し出てください（CLAUDE.md、AGENTS.md、GEMINI.md など、ユーザーのエージェントがセッション開始時に読み込むファイル）。Edit/Write ツールを使えるので、ユーザーが手動でスニペットを貼り付ける必要はありません。設定ファイルはユーザーのものなので、先に確認してください。許可を得たら、直接編集してください。

最初から最後までの手順

1. User asks for a capability (missing MCP feature, or a workflow they want
   the agent to be able to invoke).
2. You: "I can build a workflow that exposes this as a tool the MCP can call.
   Want me to create it?"
3. User: yes.
4. You build the workflow:
   - Trigger: Execute Workflow Trigger with declared inputs.
   - Body: whatever logic the tool needs (HTTP Request to n8n's API, a
     third-party call, internal computation).
   - Output: structured response.
5. Validate, test, publish.
6. Ask the user if you can add an entry for this tool to their agent context
   file (CLAUDE.md / AGENTS.md / etc.) so future sessions know to search for
   it by name. Edit the file directly when they say yes.
7. The workflow is immediately callable: agent-created workflows have `availableInMCP: true` set by default.

よくあるケース 1 のラッパー（MCP が対応していない機能）

役立つ順に、よくあるパターンを示します。ケース 2（汎用エージェントツール）はプロジェクトごとに異なるため、標準的な例はありません。

n8n REST API リファレンス： https://docs.n8n.io/api/api-reference/。ケース 1 のラッパーを作成する場合は、まずここを確認してください。エンドポイントを見つけたら、HTTP Request ノードと n8nApi 認証情報を使ってラップします。セルフホストのインスタンスでは、<instance-url>/api/v1/ からアクセスできます。

1. フォルダの削除とプロジェクト管理

MCP はフォルダの作成、名前変更、移動をネイティブに実行できるようになったため（create_folder、update_folder、move_workflows_to_folder）、これらをラップする必要はなくなりました。まだ不足しているのは、フォルダの削除と、プロジェクトの作成・名前変更です。n8n の REST API はその両方をカバーしているため（Folders エンドポイント）、一度ラップすればこのギャップを埋められます。

Tool: delete folder
Input: { projectId: string, folderId: string }
Output: { success: boolean }

2. インスタンスのメタデータ

バージョン、設定済みの連携、環境情報。SessionStart のドリフトチェックや、インスタンスの機能に合わせてワークフローを適応させるのに役立ちます。

Tool: get instance info
Input: {}
Output: { version, edition, integrations: [...], limits: {...} }

エージェントがツールワークフローを呼び出す仕組み

MCP は、ツールフラグが付いた各ワークフローを個別名の MCP ツールとして登録しません。 検出と実行は 2 ステップです。

1. search_workflows({ query: '<keyword>' }) で検出します。MCP アクセスが有効なワークフローは availableInMCP: true を返すので、それでフィルタリングします。
2. execute_workflow({ workflowId, inputs }) で実行します。まず get_workflow_details で入力スキーマを読み取ります。Execute Workflow Trigger が型付きフィールドを定義します。

出力は、ワークフローの最後のノードが返すものになります。

MCP アクセスのデフォルト: エージェントが作成したワークフローはデフォルトで availableInMCP: true になります。UI で作成したワークフローはデフォルトでオフの場合があり、その場合は検索結果に表示される前に、ユーザーがワークフロー設定で MCP アクセスをオンに切り替える必要があります。いずれの場合も、ユーザーは後からオフにしてアクセスを制限できます。

これがエージェントのコンテキストファイルのスニペット（CLAUDE.md / AGENTS.md など）が重要である理由です。 今後のセッションはツールワークフローを自動的に列挙しません。スニペットがツールの存在を名前で伝えることで、実装を再導出するのではなく、そのツールを検索するようになります。

アンチパターン

アンチパターン	何が問題になるか	修正方法
ユーザーに確認せずに MCP 拡張ワークフローを構築する	ユーザーのインスタンス上に、認証情報付きのワークフローが勝手に作成される	常に最初に許可を求める
新しいツールをエージェントのコンテキストファイルに記載しない	今後のセッションはツールワークフローを自動的に列挙しません。ヒントがないと実装を再導出してしまいます。	ユーザーに確認したうえで、CLAUDE.md / AGENTS.md / エージェントが読み取る任意のファイルを直接編集します。ユーザーにスニペットを貼り付けさせないでください。
HTTP Request ノードに n8n API トークンをハードコードする	ワークフローをエクスポートまたはコピーした際にトークンが漏洩する	タイプ n8nApi の認証情報、または適切なヘッダー認証を使用する
名前や説明に副作用の記載がない副作用のあるツール	エージェントが読み取りだと思って実行し、実際にメッセージを送信したりデータを書き込んだりしてしまう	副作用を名前と説明に明示する（例: Tool: send Slack message）。ケース 1 のラッパーでは、読み取り専用がより安全なデフォルトです。
ドライランなしで一括操作や破壊的操作（アーカイブ、削除）を行うラッパー	1 つのバグが多くのワークフローに影響する	呼び出しごとに強い明示的なオプトインを要求し、対象を一覧表示するだけで実行しないドライランモードを用意する
ラッパーが認証情報の値を返す	ツール出力経由でトークンが漏洩する	ID、名前、タイプのみを返す。シークレットは決して返さない。
ラッパーで validate + verify + test サイクルを省略する	「ツール」自体が壊れており、紛らわしいツール未検出エラーや空レスポンスエラーとして現れる	他のワークフローと同じライフサイクルです。n8n-workflow-lifecycle-official を参照してください