n8n-extending-mcp

n8n の MCP 拡張

MCP アクセスを有効にした n8n ワークフローは、コーディングエージェントが名前で呼び出せるツールになります。よくあるケースは 2 つあります。

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

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

どのような場合に使うか

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

• フォルダーの CRUD（作成、名前変更、移動、削除）：REST API はありますが、MCP ツールはまだありません。
• タグの名前変更／削除：MCP はタグを一覧表示（list_tags）し、追加／解除（update_workflow の addTags／removeTags。不明な名前は自動作成）できますが、タグエンティティの名前変更や削除はできません。それらには REST API があります。
• インスタンスのメタデータ（制限、プラン情報、設定済みの連携機能）：MCP ツールはありません。
• 認証情報の作成：REST API（POST /credentials）はありますが、MCP ツールはまだありません。
• MCP がネイティブに公開していない、その他の n8n API 操作。

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

• 繰り返し発生するエージェントのタスクのうち、毎回説明し直すよりコード化しておきたいもの（検索、形式の整備、送信など）。
• エージェントが直接アクセスできないシステムに対する操作（非公開 API、社内サービス、サードパーティ連携）。
• 将来のセッションで、実装方法を再導出せずに呼び出せるようにしておきたいもの。

次の用途には使わないでください。

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

必ず守ること

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

手順

• まず既存のラッパーを検索してください。 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 ではワークフローを既存のフォルダーに配置できますが、フォルダーの作成、名前変更、移動、削除はできません。n8n の REST API には Folders エンドポイントがあるため、フォルダーを頻繁に整理するユーザーは、一度ラッパーを作成すればこの機能を利用できます。

Tool: create folder
Input: { projectId: string, name: string, parentFolderId?: string }
Output: { id, name, projectId, parentFolderId? }

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、名前、タイプのみを返してください。秘密情報は絶対に返さないでください。
ラッパーの検証、確認、テストのサイクルを省略する	「ツール」自体が壊れ、ツールが見つからない、または応答が空といった分かりにくいエラーになります	他のワークフローと同じライフサイクルに従ってください：n8n-workflow-lifecycle を参照