MCP tool для внутреннего API через n8n: безопасный доступ AI к данным ¶

Обновлено: 2026-05-30

Проблема: AI и MCP tool calling дают модели доступ к действиям, но прямой вызов внутреннего API без allowlist, validation и audit превращает ассистента в рискованный proxy.

Решение: n8n должен работать как gateway: принять tool call, проверить политику, записать audit, вызвать только разрешенный endpoint и вернуть sanitized response.

Проблема: почему AI нельзя давать прямой доступ к внутреннему API ¶

MCP и tool calling делают AI полезнее: модель может запросить клиента в CRM, проверить статус заказа или подготовить ответ оператору. Но прямой доступ к внутреннему API опасен. Prompt injection может попросить модель вызвать не тот endpoint, параметры могут оказаться слишком широкими, а токен backend-а попадет в execution logs.

Безопасный подход — сделать n8n policy gateway. AI вызывает не произвольный URL, а конкретный MCP tool: `crm.find_customer`, `orders.get_status` или другой allowlisted метод. Workflow проверяет роль пользователя, JSON args, лимиты, reason, пишет audit log и только после этого обращается к внутреннему API.

Архитектура MCP tool gateway через n8n ¶

Контракт tool call и JSON args ¶

{
  "tool": "crm.find_customer",
  "request_id": "req-2026-05-30-1042",
  "actor": {
    "user_id": "u-17",
    "role": "support_agent"
  },
  "args": {
    "phone": "+7 916 123-45-67",
    "include_orders": false
  },
  "policy": {
    "environment": "production",
    "reason": "support_ticket_lookup",
    "max_rows": 3
  }
}

Контракт должен быть узким: одно действие, понятная причина вызова, минимум аргументов и жесткий лимит строк. Это помогает контролировать AI-интеграцию и не превращает MCP server в открытый proxy к внутренней сети.

Code Node: allowlist, JSON Schema и policy check ¶

const input = $json.body ?? $json;
const allowedTools = {
  'crm.find_customer': {
    roles: ['support_agent', 'admin'],
    required: ['phone'],
    max_rows: 3,
    endpoint: '/crm/customers/search'
  },
  'orders.get_status': {
    roles: ['support_agent', 'admin'],
    required: ['order_id'],
    max_rows: 1,
    endpoint: '/orders/status'
  }
};

const spec = allowedTools[input.tool];
if (!spec) throw new Error(`Tool is not allowed: ${input.tool}`);

const role = input.actor?.role;
if (!spec.roles.includes(role)) {
  throw new Error(`Role ${role} cannot call ${input.tool}`);
}

const args = input.args ?? {};
for (const field of spec.required) {
  if (!args[field]) throw new Error(`Missing required arg: ${field}`);
}

const phone = args.phone ? String(args.phone).replace(/\D/g, '') : undefined;
if (phone && !/^(7|8)\d{10}$/.test(phone)) {
  throw new Error('Invalid phone format for tool call');
}

return [{
  json: {
    request_id: input.request_id,
    tool: input.tool,
    actor: input.actor,
    endpoint: spec.endpoint,
    method: 'POST',
    sanitized_args: { ...args, phone: phone ? `+7${phone.slice(-10)}` : undefined },
    limit: Math.min(input.policy?.max_rows ?? spec.max_rows, spec.max_rows),
    audit: {
      reason: input.policy?.reason ?? 'not_provided',
      environment: input.policy?.environment ?? 'production',
      checked_at: new Date().toISOString()
    }
  }
}];

Готовый workflow JSON ¶

Скачать готовый workflow JSON Скачать тестовый payload

{
  "name": "Nodbot - MCP internal API tool gateway",
  "nodes": [
    {
      "name": "MCP tool webhook",
      "type": "n8n-nodes-base.webhook",
      "purpose": "Принять tool call от MCP client/AI gateway"
    },
    {
      "name": "Validate allowlist and args",
      "type": "n8n-nodes-base.code",
      "purpose": "Проверить tool name, роль, аргументы и policy"
    },
    {
      "name": "Write audit log",
      "type": "n8n-nodes-base.postgres",
      "purpose": "Сохранить request_id, actor, reason и sanitized args"
    },
    {
      "name": "Call internal API",
      "type": "n8n-nodes-base.httpRequest",
      "purpose": "Вызвать только разрешенный endpoint"
    },
    {
      "name": "Sanitize response",
      "type": "n8n-nodes-base.code",
      "purpose": "Убрать лишние поля до возврата AI"
    },
    {
      "name": "Respond to MCP client",
      "type": "n8n-nodes-base.respondToWebhook",
      "purpose": "Вернуть безопасный JSON result"
    }
  ],
  "connections": "Webhook → Validate → Audit → API → Sanitize → Respond"
}

Пошаговая настройка MCP tool, n8n и внутреннего API ¶

1. Опишите список разрешенных tools: имя, роли, аргументы, endpoint и лимиты.
2. Создайте Webhook в n8n как gateway для MCP client или AI orchestration слоя.
3. Добавьте Code Node для allowlist, role check и нормализации аргументов.
4. Пишите audit log до вызова backend-а, чтобы видеть даже запрещенные попытки.
5. Возвращайте AI только sanitized response, без секретов, внутренних id и лишних PII.

Тесты перед production ¶

curl -X POST "https://YOUR-N8N-DOMAIN/webhook/mcp-internal-api-tool" \
  -H "Content-Type: application/json" \
  --data @mcp-internal-api-tool-payload.json

Проверьте разрешенный tool, неизвестный tool, роль без доступа, отсутствующий required arg, слишком широкий лимит и prompt injection в текстовом поле. Запрещенные кейсы должны завершаться контролируемой ошибкой и audit-записью.

Production-риски MCP и tool calling ¶

• Overprivileged credentials. Токен n8n не должен иметь доступ ко всему backend-у.
• Prompt injection. Модель может попытаться вызвать другой tool или запросить больше данных.
• Нет audit log. Нельзя расследовать, кто и зачем вызвал внутренний API.
• Слишком широкий response. Возвращайте минимум полей, нужных для ответа.
• Ошибки backend-а видит пользователь. Убирайте stack trace и внутренние URL из ответа AI.

Полезные ссылки и смежные workflow ¶

См. также права AI-агентов, архитектуру AI-агентов, проверку подписи webhook и GigaChat support draft. Официальные документы: Model Context Protocol, MCP Specification и n8n Webhook node.

Критерии готовности ¶

1. Каждый tool есть в allowlist с ролями и лимитами.
2. Аргументы валидируются до вызова внутреннего API.
3. Audit log пишется для разрешенных и запрещенных попыток.
4. Ответ AI содержит только минимально нужные поля.
5. Секреты backend-а хранятся в credentials/ENV, а не в payload.