У нас есть корпоративные MCP-серверы, AI-агент и пользователи в Telegram. Каждый пользователь должен авторизоваться через Keycloak, а агент — работать от его имени. Здесь собраны грабли, на которые мы наступили, и архитектурные решения, к которым пришли.
Кому это будет полезно
Если вы:
Прикручиваете OAuth/OIDC к чему-то, что на это не рассчитано
Строите мультитенантного AI-агента, где у каждого пользователя свои права
Пытаетесь подружить MCP-серверы с корпоративным IdP
Пишете кастомные ноды для n8n
Исходная архитектура
MCP (Model Context Protocol) — открытый стандарт от Anthropic для подключения AI-моделей к внешним инструментам. У нас несколько MCP-серверов, перед ними — глобальный прокси на FastMCP, который агрегирует все в единую точку входа.
Глобальный прокси работал, но не знал, кто делает запрос. Любой, кто достучится до порта, получает доступ ко всему. Для внутренней разработки это терпимо, но для бота с сотнями пользователей — уже нет.
Выбор архитектуры: почему отдельный сервис
Первый порыв — засунуть проверку токена прямо в прокси. Быстро поняли, что не хотим мешать маршрутизацию с авторизацией в одном процессе. Gateway обновляется при каждом изменении конфигурации MCP-серверов, а авторизация — штука, которую лучше менять как можно реже.
Второй вариант — встроить авторизацию в каждый MCP-сервер. Но их у нас достаточно, и каждый пришлось бы учить ходить в Keycloak. А если завтра мы сменим IdP — переделывать все.
Остановились на отдельном Auth Proxy перед Gateway. Да, это еще один сервис в деплое и лишние 3-5 миллисекунд на каждый запрос. Но когда основное время уходит на LLM (2-4 секунды), эти миллисекунды роли не играют. Зато Gateway остается чистым агрегатором, а вся логика авторизации живет в одном месте.
В FastMCP для этого есть OAuthProxy — он представляется MCP-клиентам как полноценный OAuth-сервер с поддержкой Dynamic Client Registration, а за кулисами использует заранее зарегистрированные credentials с Keycloak. Пароль пользователя при этом вводится только в браузере на странице Keycloak — Auth Proxy его никогда не видит.
Грабли OAuth
Из десятка проблем, с которыми столкнулись, 2 отняли больше всего времени.
Кто на самом деле генерирует ошибку
При подключении через n8n получали invalid_scope: Client was not registered with scope openid. Полезли проверять настройки клиента в Keycloak — scope openid там был. Стали грешить на конфигурацию realm.
А потом посмотрели на домен в URL редиректа. Там был наш домен, а не Keycloak. Ошибку генерировал OAuthProxy — scope openid не был в его внутреннем списке valid_scopes, и запрос отклонялся еще до того, как дошёл до Keycloak.
С тех пор правило: при OAuth-ошибках первым делом смотрим домен в URL редиректа — сразу видно, кто именно отклонил запрос.
Клиенты на разных диалектах OAuth
n8n MCP Client Tool не отправляет PKCE (code_challenge), а OAuthProxy его требует. Еще n8n передает credentials через Basic Auth header, а OAuthProxy ожидает client_id в теле POST.
Патчить n8n или лезть в кишки OAuthProxy не хотелось — оба обновляются независимо. Написали middleware-прослойку, которая сглаживает различия:
# single-worker, для масштабирования нужен Redis
class PKCEInjectorMiddleware(BaseHTTPMiddleware):
"""
Подставляет PKCE за клиентов, которые его не отправляют.
Конвертирует Basic Auth в POST-параметры для совместимости
с OAuthProxy.
"""
verifiers: dict[str, str] = {}
async def dispatch(self, request, call_next):
if request.url.path == "/authorize":
params = dict(request.query_params)
if "code_challenge" not in params:
# Клиент не поддерживает PKCE — генерируем за него
verifier = secrets.token_urlsafe(64)
challenge = base64.urlsafe_b64encode(
hashlib.sha256(verifier.encode()).digest()
).rstrip(b"=").decode()
state = params.get("state", "")
if state:
self.verifiers[state] = verifier
params["code_challenge"] = challenge
params["code_challenge_method"] = "S256"
# Переписываем query string
...
if request.url.path == "/token":
body = await request.body()
body_str = body.decode()
# Подставляем сохраненный code_verifier
if "code_verifier" not in body_str and self.verifiers:
for sv, ver in list(self.verifiers.items()):
body_str += f"&code_verifier={ver}"
del self.verifiers[sv]
break
# Конвертируем Basic Auth → POST body
if "client_id" not in body_str:
auth_header = request.headers.get("authorization", "")
if auth_header.startswith("Basic "):
decoded = base64.b64decode(auth_header[6:]).decode()
client_id, client_secret = decoded.split(":", 1)
body_str += f"&client_id={client_id}"
body_str += f"&client_secret={client_secret}"
...
return await call_next(request)
Middleware между OAuth-прокси и клиентами оказался на удивление универсальным паттерном. Один класс закрыл две проблемы, и если завтра появится клиент с еще каким-нибудь «диалектом» — добавим обработку туда же, не трогая ни OAuthProxy, ни клиент.
Per-user авторизация: фундаментальная проблема
OAuth заработал, но обнаружилась проблема, которую настройками не решить.
n8n MCP Client Tool авторизуется один раз — при настройке credential. Все запросы через workflow идут от имени того, кто прошел OAuth.
Когда Иванов пишет боту, MCP-сервер видит не Иванова, а администратора, настроившего credential. Для бота с разграничением прав это не работает. Нужна другая схема:
Добавили в Auth Proxy набор эндпоинтов — User Auth API. Полный flow:
Пользователь пишет боту «привет»
Бот → POST /user-auth/start {“user_id”: “telegram_12345”}
Auth Proxy проверяет: есть ли активная сессия?
Если токен валиден → {status: “completed”, session_id: “abc”}
Если токен истек → пробует refresh_token
Если refresh невалиден → создает новую сессию
Auth Proxy → 201 {session_id: “abc”, login_url: “https://keycloak…/auth?..”}
Бот отправляет пользователю кнопку с login_url
Пользователь кликает → браузер → страница логина Keycloak
Пользователь вводит логин/пароль (на странице Keycloak, не в боте!)
Keycloak → redirect на /user-auth/callback с одноразовым code
Auth Proxy обменивает code на access_token + refresh_token, сохраняет
Бот → GET /user-auth/status/abc → {status: “completed”, username: “Иванов”}
Бот → POST /user-auth/mcp (headers: x-session-id: abc) Body: {jsonrpc: “2.0”, method: “tools/call”, params: {name: “whoami”}}
Auth Proxy подставляет Bearer token Иванова → Gateway → MCP-сервер
Результат возвращается обратно по цепочке
Токены хранятся только в Auth Proxy. Бот работает исключительно с session_id — идентификатором, который сам по себе бесполезен без Auth Proxy.
Три канала через одну дверь
В итоге Auth Proxy обслуживает три типа клиентов через единый Keycloak:
Claude Desktop подключается напрямую — достаточно указать URLв конфиге. Claude сам проходит OAuth flow: читает метаданные сервера, регистрируется через Dynamic Client Registration, открывает браузер для логина в Keycloak. Per-user из коробки.
n8n MCP Client Tool — стандартный OAuth2 с Dynamic Client Registration. Один credential на workflow. Подходит для сервисных задач.
Telegram-бот — per-user авторизация через User Auth API. Каждый пользователь получает персональную ссылку на Keycloak.
Кастомная нода для n8n: usableAsTool
Хотели сделать AI Tool-ноду для n8n, чтобы AI Agent вызывал MCP-инструменты от имени конкретного пользователя.
Перепробовали четыре подхода — supplyData с DynamicTool, DynamicStructuredTool с Zod, внутренние пакеты n8n (StructuredToolkit, logWrapper), ручную подмену schema через Object.defineProperty. Каждый упирался в одно: встроенные AI tool-ноды n8n используют внутренние пакеты монорепозитория, недоступные кастомным нодам.
Решение нашлось в community-ноде Merge Agent Handler — одно недокументированное свойство:
description: INodeTypeDescription = {
usableAsTool: true, // n8n автоматически оборачивает ноду в AI Tool
inputs: [NodeConnectionTypes.Main],
outputs: [NodeConnectionTypes.Main],
};
usableAsTool: true говорит n8n: возьми обычную ноду с execute() и сделай из нее AI Tool. Без supplyData, без LangChain, без внутренних пакетов. Параметры разделяются на два режима через displayOptions с @tool:
// Standalone — пользователь вводит вручную
{ name: 'toolName', displayOptions: { hide: { '@tool': [true] } } }
// Agent — AI Agent заполняет автоматически
{ name: 'toolNameAgent', displayOptions: { show: { '@tool': [true] } } }
Переход на LangGraph
Кастомная нода заработала. Но столкнулись с архитектурной проблемой, которую в рамках n8n решить не удалось.
Одна tool вместо двенадцати
Встроенный MCP Client Tool регистрирует каждый MCP-инструмент как отдельную tool — со своим именем, описанием и схемой параметров. usableAsTool: true делает из ноды одну tool. Все 12 инструментов приходится упаковывать в «мета-тулзу»:
На простых запросах работало. На сложных — LLM путалась: формировала неправильный JSON, путала имена инструментов, передавала аргументы не в том формате. Когда у агента 12 отдельных tools с четкими схемами — он знает, что делать. Когда одна «мета-тулза» с описанием на полстраницы — начинает импровизировать.
Что рассматривали перед тем, как уйти
Форкнуть встроенный MCP Client Tool — заманчиво, потому что получаем StructuredToolkit и 12 отдельных tools. Но это привязка к внутренним API n8n, которые не являются публичным контрактом и ломаются между версиями. Для продакшна слишком хрупко.
Создать несколько экземпляров кастомной ноды — по одной на каждый инструмент. Работает, но при добавлении инструмента на MCP-сервере нужно руками добавлять ноду в workflow. У нас 12 инструментов и число растет.
LangGraph — теряем визуальный конструктор n8n. Но для бота в Telegram этот конструктор и не нужен: весь workflow — это один блок «вызвать агента». А вот per-user state и 12 отдельных tools с правильными схемами — нужны. Выбор был довольно очевиден.
В LangGraph каждый MCP-инструмент регистрируется как отдельная tool с собственной схемой параметров. Агент сам управляет авторизацией — проверяет токены, генерирует ссылки, обновляет сессии. Это код, а не набор middleware и хаков.
Auth Proxy при этом остался в архитектуре — обслуживает Claude Desktop и n8n через OAuthProxy. LangGraph-бот ходит к нему через User Auth API.
Что получилось в цифрах
Три канала доступа к MCP-серверам через один Auth Proxy: Claude Desktop, n8n для сервисных задач, Telegram-бот с per-user авторизацией.
Авторизация нового пользователя занимает секунд 15 — кликнуть по ссылке, ввести логин-пароль на странице Keycloak, вернуться в чат. Повторный логин нужен раз в 30 дней (настраивается на стороне Keycloak), все остальное время токены обновляются автоматически через refresh_token.
Переход с n8n на LangGraph занял три дня. User Auth API в Auth Proxy не пришлось менять — поменялся только клиент. Это, пожалуй, лучшее подтверждение того, что решение вынести авторизацию в отдельный сервис было правильным.
Все 12 MCP-инструментов зарегистрированы как отдельные tools в LangGraph — каждый со своей схемой параметров. LLM перестала путать инструменты и формировать невалидный JSON, что было главной проблемой с «мета-тулзой» в n8n.
Известные ограничения
Session storage в памяти. Auth Proxy хранит сессии in-memory. При рестарте все пользователи должны авторизоваться заново. В планах — Redis.
Нет rate limiting. Auth Proxy не ограничивает частоту запросов. Пока это не проблема, но при масштабировании придется добавить.
PKCE Injector — компромисс безопасности. Мы генерируем PKCE за клиента, что ослабляет защиту, которую PKCE призван обеспечить. Допустимо для внутренней инфраструктуры, но для публичного сервиса нужно требовать PKCE от самих клиентов.
Выводы
Middleware между OAuth-прокси и клиентами — на удивление универсальный паттерн. Один класс закрыл PKCE и Basic Auth, и расширяется при появлении новых клиентов без изменения OAuthProxy или самих клиентов.
usableAsTool: true в n8n — недокументированное свойство, которое превращает обычную ноду в AI Tool. Работает, но с ограничением: одна tool, а не набор. Для простых сценариев достаточно, для сложных — LLM начинает путаться.
Выбор платформы — n8n хорошо подходит для сервисных интеграций с одним credential на workflow. Для per-user авторизации с десятком инструментов фреймворк вроде LangGraph дает больше контроля и меньше борьбы с платформой.
Ссылки:
P.S. Если у вас похожая задача или вы нашли способ зарегистрировать несколько tools через кастомную ноду n8n — буду рада обратной связи через Issues на GitHub