Запуск кастомных MCP-прокси без серверов на Amazon Bedrock AgentCore Runtime

Когда AI-агенты подключаются к инструментам через Model Context Protocol (MCP), они получают доступ к возможностям, которые включают запросы к базам данных, вызовы API, операции с файлами и интеграции со сторонними сервисами. В продакшене таким взаимодействиям нужны надлежащее управление, контроль и наблюдаемость в соответствии с политиками безопасности организации. Это может включать очистку входных данных инструментов до того, как они попадут в backend-системы, формирование audit trail в заданном формате или маскирование чувствительных данных на уровне протокола. Эти требования определяются внутренними стандартами управления, отраслевыми нормами и особенностями конкретной производственной среды. В этой статье показано, как развернуть serverless MCP-прокси на Amazon Bedrock AgentCore Runtime, чтобы получить программируемый слой для реализации этих контролей.

Amazon Bedrock AgentCore Gateway обеспечивает централизованное управление и контроль для интеграции агентов с инструментами, включая семантическое обнаружение инструментов, управляемые учетные данные и enforcement политик. Для организаций, которым нужно внедрить собственную логику в путь запроса Gateway, поддерживает Lambda interceptors. Такие interceptors позволяют запускать код валидации, преобразования или фильтрации как функции AWS Lambda при каждом вызове инструмента. Это позволяет держать кастомную логику изолированной и управляемой вместе с конфигурацией Gateway.

Однако у некоторых организаций уже есть собственная MCP-логика фильтрации, тесно связанная с внутренними библиотеками или on-premises системами compliance. Они хотят использовать ее на AgentCore Runtime без переноса в функции Lambda. Другие работают в нескольких системах или в гибридных средах, где запуск контролей как отдельного MCP-сервера дает большую портируемость, чем системно-специфичный interceptor. В таких случаях serverless MCP-прокси, работающий на AgentCore Runtime, может стать дополнительным паттерном.

AgentCore Runtime — это полностью управляемая вычислительная среда для развертывания AI-агентов и MCP-серверов. Она предоставляет serverless-инфраструктуру с автоматическим масштабированием, встроенной наблюдаемостью через Amazon CloudWatch и OpenTelemetry, а также AgentCore Identity для аутентификации и авторизации. Поскольку Runtime нативно поддерживает протокол MCP, он позволяет размещать MCP-серверы, включая MCP-прокси, которые добавляют пользовательские контроли к MCP-трафику.

Мы показываем, как построить и развернуть stateless MCP-прокси на AgentCore Runtime, который позволяет добавлять программируемые контроли к MCP-трафику. Прокси работает как serverless-нагрузка в Runtime, при запуске обнаруживает инструменты на upstream MCP-сервере, повторно публикует их с применением вашей кастомной логики и прозрачно пересылает запросы. Upstream MCP-сервер может быть любым MCP-совместимым endpoint, включая MCP-серверы на AgentCore Runtime, self-hosted MCP-серверы или сторонние MCP-сервисы. Также можно подключить этот прокси к Amazon Bedrock AgentCore Gateway. Это дает возможность использовать управляемое обнаружение инструментов, управление учетными данными и enforcement политик Gateway для MCP-серверов, функций Lambda и SaaS-интеграций.

Используя open source-реализацию на GitHub как основу, мы пошагово разбираем архитектуру, объясняем, как работает авторизация на каждом уровне, разворачиваем прокси с помощью автоматизированного скрипта и тестируем end-to-end поток с примером агента. В итоге получается рабочий шаблон развертывания для добавления кастомных контролей к MCP-трафику с помощью AgentCore Runtime.

Обзор решения

Кастомный MCP-прокси работает на AgentCore Runtime и выступает посредником между MCP-клиентами и upstream MCP-серверами. MCP-клиенты взаимодействуют с прокси так же, как и с другими MCP-серверами; прокси применяет специализированную логику и пересылает запросы на upstream-сервер. Такое разделение позволяет внедрять пользовательские контроли на уровне протокола без изменения upstream MCP-сервера или клиента.

Компоненты архитектуры

Решение состоит из трех логических уровней, которые работают вместе через MCP: MCP-клиент, MCP-прокси на AgentCore Runtime и upstream MCP-сервер. Поток запросов последовательно проходит через эти уровни: клиент отправляет MCP-запросы в прокси, прокси применяет кастомную логику и пересылает запрос на upstream MCP-сервер, а upstream-сервер обрабатывает запрос и возвращает ответ обратно тем же путем.

Upstream MCP-сервер может быть размещен где угодно, включая AgentCore Runtime, вашу собственную инфраструктуру или сторонний сервис. В этой статье в качестве upstream MCP-сервера используется AgentCore Gateway, поскольку он предоставляет готовую MCP-совместимую точку доступа к инструментам с зарегистрированными целями, позволяя пройти весь walkthrough end-to-end без разворачивания отдельного MCP-сервера. Подход с прокси применим и к другим MCP-совместимым upstream endpoint, а альтернативы рассматриваются по всему материалу, включая upstream MCP-серверы, работающие на AgentCore Runtime.

Следующая схема показывает архитектуру, включая потоки запросов и аутентификации:

MCP-клиент в Runtime рассматривает кастомный MCP-прокси как свой tool server, отправляя стандартные MCP-запросы для обнаружения и вызова инструментов. С точки зрения клиента прокси неотличим от других MCP-серверов. AgentCore Runtime обеспечивает управляемые вычисления, автоматическое масштабирование и встроенную наблюдаемость для нагрузки клиента.

MCP-прокси действует как посредник между клиентом и upstream MCP-сервером. Он получает MCP-запросы от клиента, применяет вашу кастомную логику и пересылает запросы на upstream-сервер. Прокси запускается как отдельный MCP-сервер в Runtime, используя ту же serverless-управляемую инфраструктуру, что и сам клиент.

Прокси подключается к upstream MCP-серверу как стандартный MCP-клиент. Upstream-сервер рассматривает прокси как аутентифицированного MCP-клиента, ничем не отличающегося от других авторизованных вызывающих сторон. Upstream-сервер управляет доступом к downstream-сервисам и MCP-инструментам.

Сами инструменты, независимо от того, размещены ли они как MCP servers, AWS Lambda functions или сторонние SaaS-интеграции, регистрируются и управляются upstream-сервером. Для организаций, которым нужен полностью управляемый путь к интеграции инструментов, AgentCore Gateway предлагает простой и безопасный способ для разработчиков создавать, разворачивать, находить и подключать инструменты в масштабе.

Как работает MCP-прокси

Мы реализуем прокси с помощью FastMCP, чтобы при запуске обнаруживать инструменты на upstream MCP-сервере и пересылать каждый запрос клиента во время работы. Прокси не определяет собственные инструменты и заранее не знает, что именно предоставляет upstream-сервер.

Когда процесс прокси запускается, он отправляет стандартный MCP-запрос tools/list на upstream-сервер. Сервер возвращает полный каталог доступных инструментов. Для каждого инструмента прокси динамически регистрирует локальный инструмент FastMCP с тем же именем и описанием. За каждым инструментом стоит handler-функция, которая пересылает запросы tools/call на upstream-сервер и возвращает ответ. MCP-клиенты, подключающиеся к прокси, видят тот же каталог инструментов и получают те же результаты, как если бы они подключались напрямую к upstream-серверу.

Поскольку прокси — это стандартный Python MCP-сервер, которым вы владеете и который вы разворачиваете сами, вы можете вставлять кастомную логику до пересылки вызова инструмента или после получения ответа. Upstream-сервер отвечает за выполнение инструментов, а прокси добавляет перед ним программируемый слой, не заменяя нативные возможности upstream-сервера.

Авторизация между компонентами

Авторизация enforced отдельно на каждом уровне архитектуры, создавая отдельные trust boundaries на всем пути прохождения запроса.

• Agent to MCP proxy: Когда агент подключается к MCP-прокси, он использует AgentCore Identity для аутентификации и авторизации. Прокси использует возможности, которые предоставляет AgentCore Identity, включая централизованное управление идентификаторами агентов и безопасное хранение учетных данных. Вы контролируете, какие агенты и principals могут вызывать прокси, используя ту же identity framework, что и для других нагрузок в AgentCore Runtime.
• Proxy to upstream MCP server: Прокси должен аутентифицироваться на upstream MCP-сервере, к которому он подключается. Метод аутентификации зависит от требований upstream-сервера. AgentCore Identity предоставляет inbound authorization для workloads, размещенных на AgentCore Runtime, как через AWS Identity and Access Management (IAM) с использованием AWS Signature Version 4 (SigV4), так и через JSON Web Token (JWT)-based authorization с использованием OAuth 2.0 client credentials. При JWT-based authorization вы настраиваете upstream-сервер с discovery URL, разрешенными audiences и разрешенными clients. AgentCore Identity проверяет bearer token при каждом запросе. Прокси получает токены через OAuth 2.0 client credentials grant и добавляет их как заголовки Authorization: Bearer .

При IAM-based authorization прокси подписывает запросы с помощью AWS SigV4, используя IAM execution role, унаследованную от AgentCore Runtime. Конкретные права зависят от типа upstream-сервера. Если upstream MCP-сервер размещен на AgentCore Runtime, вы ограничиваете право bedrock-agentcore:InvokeAgentRuntime, чтобы контролировать, какие вызывающие стороны могут до него достучаться. Если же upstream-сервер — AgentCore Gateway, как в этом walkthrough, вы ограничиваете bedrock-agentcore:InvokeGateway конкретными Gateway и идентичностями вызывающих сторон. Это гарантирует, что доступ к каталогу инструментов получат только доверенные прокси.

Сопутствующий проект на GitHub использует IAM-based authorization как метод по умолчанию. Скрипт развертывания также поддерживает JWT-based authorization для этой интеграции.

• Upstream server to tools: Upstream MCP-сервер аутентифицируется к downstream-инструментам с помощью AgentCore Identity credential providers, которые прозрачно управляют OAuth 2.0 tokens, API keys и ротацией учетных данных. Outbound authorization работает одинаково независимо от того, приходят ли запросы от прокси или напрямую от клиента.

Каждый уровень в этой архитектуре аутентифицируется независимо. Вы внедряете кастомную логику на уровне MCP-протокола через прокси, а upstream-сервер продолжает выполнять инструменты и управлять своей авторизацией. В результате получается архитектура, где кастомные контроли и upstream-возможности работают в отдельных, четко определенных слоях.

Требования

Чтобы реализовать решение, вам понадобятся следующие компоненты:

• Linux- или macOS-среда разработки с установленным Python 3.12 или новее. Это может быть локальный компьютер или облачный инстанс.
• AWS Command Line Interface (AWS CLI), установленный и настроенный с учетными данными для principals AWS Identity and Access Management (AWS IAM), у которого есть права на создание IAM roles, работу с Amazon Elastic Container Registry (Amazon ECR) и вызов API Amazon Bedrock AgentCore. Если у вас нет аккаунта AWS, см. How do I create and activate a new Amazon Web Services account?
• AgentCore starter toolkit, установленный в вашей среде разработки. Этот инструмент упаковывает и развертывает агентов в AgentCore Runtime. Если у вас нет AgentCore starter toolkit, см. Get started with the Amazon Bedrock AgentCore starter toolkit in Python.
• Docker, установленный в вашей среде разработки. AgentCore CLI использует Docker для сборки контейнерного образа, который работает в AgentCore Runtime.
• Upstream MCP-серверный endpoint, к которому будет подключаться прокси. В этом walkthrough мы используем Amazon Bedrock AgentCore Gateway как минимум с одним зарегистрированным target. Если у вас нет AgentCore Gateway, см. Create an Amazon Bedrock AgentCore gateway. После создания запишите URL Gateway MCP endpoint. Он понадобится для настройки прокси.
• (Если ваш upstream-сервер использует OAuth inbound authorization) Amazon Cognito user pool с настроенным доменом и app client, использующим client credentials grant с client secret. Если вы создали Gateway с помощью AgentCore starter toolkit и OAuth authorization, эти ресурсы будут созданы автоматически при развертывании Gateway.

Развертывание решения

Выполните следующие шаги, чтобы развернуть проект в своем аккаунте AWS:

1. Сначала клонируйте репозиторий на GitHub и изучите структуру проекта.
2. Откройте deploy_config.json и задайте значения для своей среды:
   

   

   Замените значение в gateway_endpoint на URL MCP endpoint вашего upstream MCP-сервера (в этом примере — AgentCore Gateway). Укажите region как AWS Region, в котором развернут upstream-сервер. Поле gateway_api_id необязательно. Если ваш upstream-сервер — AgentCore Gateway и вы укажете его Amazon Resource Name (ARN), скрипт развертывания ограничит IAM permissions именно этим ресурсом. Если оставить значение null, скрипт выдаст права на вызов всех Gateway в аккаунте.

   Поле auth_mode определяет, как прокси аутентифицируется на upstream-сервере, и по умолчанию имеет значение "iam" для IAM-based authentication. Если установить auth_mode в "jwt" для OAuth-based authentication, необходимо заполнить поля Cognito (cognito_user_pool_id, cognito_client_id и cognito_domain) значениями из вашего Cognito user pool. Затем передайте client secret для Cognito через флаг --cognito-client-secret при запуске скрипта развертывания. При использовании IAM authentication оставьте все поля Cognito равными null.

3. Запустите автоматизированный скрипт развертывания setup_and_deploy.py из корня проекта. Он автоматизирует полный workflow развертывания, который последовательно выполняет следующие шаги:
   1. Проверяет prerequisites — убеждается, что доступны AWS CLI, Python и Docker, а также что настроены AWS credentials.
   2. Создает IAM execution role — создает роль с trust policy, которая позволяет bedrock-agentcore.amazonaws.com принимать эту роль на себя. Роль включает права на вызов Gateway, запись в логи Amazon CloudWatch и загрузку образов из Amazon ECR.
   3. Настраивает agent с помощью AgentCore CLI — запускает agentcore configure с MCP protocol, указывая на entrypoint прокси в mcp_proxy/main.py. На этом шаге CLI предложит выбрать репозиторий ECR и подтвердить режим аутентификации.
   4. Запускает agent в AgentCore Runtime — выполняет agentcore launch и передает endpoint upstream-сервера как environment variable (GATEWAY_ENDPOINT). AgentCore Runtime собирает контейнерный образ, отправляет его в Amazon ECR и запускает agent.
4. Проверьте статус MCP proxy agent: agentcore status --agent mcp_proxy. Запишите ARN агента из вывода. Он понадобится в test client agent для последующего вызова прокси.

Как настроить метод аутентификации прокси

Режим аутентификации между MCP-прокси и upstream-сервером зависит от того, как настроена inbound authorization на upstream-сервере. AgentCore Identity поддерживает как IAM, так и JWT inbound authentication для workloads, размещенных на AgentCore. Код прокси на GitHub реализует каждый режим в одной функции _send_gateway_request, где выполняются outbound HTTP-вызовы к upstream-серверу.

IAM authorization

Прокси подписывает каждый исходящий запрос к upstream-серверу с помощью AWS SigV4. Поскольку прокси работает на AgentCore Runtime, он наследует IAM execution role, указанную во время развертывания. Скрипт развертывания выдает этой роли право bedrock-agentcore:InvokeGateway с полем Resource, ограниченным Gateway. Дополнительные учетные данные или токены не требуются. Прокси автоматически использует сессию boto3 в runtime для подписи запросов.

OAuth authorization

Если upstream-сервер использует JWT authorizer, прокси заменяет подпись SigV4 на bearer token, полученный через OAuth 2.0 client credentials grant. Этот режим встроен в прокси и не требует изменений кода. Нужно установить auth_mode в jwt в конфигурации развертывания и указать сведения о Cognito user pool.

Когда вы выбираете JWT, скрипт собирает идентификатор Cognito user pool, app client ID, app client secret и prefix домена. Эти значения передаются контейнеру AgentCore Runtime как environment variables на этапе agentcore launch. Их также можно задать напрямую в deploy_config.json, чтобы пропустить интерактивные запросы.

При запуске прокси считывает переменную среды AUTH_MODE. Если она установлена в jwt, прокси запрашивает access token с использованием HTTP authentication и client credentials. Токен кешируется в памяти и автоматически обновляется, когда приближается к истечению срока действия. Каждый исходящий запрос к upstream MCP-серверу включает токен в заголовке Authorization: Bearer вместо SigV4 signature headers.

Остальная часть прокси (обнаружение инструментов, пересылка инструментов и FastMCP server) работает одинаково независимо от режима аутентификации. Единственное отличие — то, как _send_gateway_request аутентифицирует исходящие вызовы.

Тестирование решения

В репозитории есть test_agent.py — скрипт Strands Agents, который подключается к MCP-прокси, работающему на AgentCore Runtime, и использует обнаруженные инструменты.

Агент подключается к прокси, а не к upstream-серверу, обращаясь к endpoint AgentCore Runtime для развернутого прокси. Он отправляет MCP JSON-RPC-запросы для обнаружения инструментов и их вызова. Следующая запись экрана показывает CLI-сеанс, в котором агент обнаруживает инструменты через прокси и использует их, чтобы интерактивно отвечать на вопросы.

В этом примере upstream-сервер (AgentCore Gateway) предоставляет инструменты для арифметических операций, а агент действует как калькулятор, использующий эти инструменты для простых вычислений.

Варианты кастомизации

Архитектура прокси позволяет перехватывать и преобразовывать MCP-трафик между клиентом и upstream MCP-сервером. Следующие примеры демонстрируют два распространенных паттерна кастомизации:

Токенизация

Аргументы вызова инструмента могут содержать personally identifiable information (PII), которое не должно попадать в backend-системы в открытом виде. Поток пересылки в прокси дает естественную точку перехвата для добавления токенизации.

Вот как работает поток: когда клиент вызывает инструмент, функция _make_tool_handler в main.py получает аргументы в виде словаря kwargs, передает их в _send_gateway_request, который упаковывает их в JSON-RPC payload и отправляет (подписав SigV4) на upstream MCP-сервер, а затем форматирует ответ обратно для клиента. Соответствующий код выглядит так:

def _make_tool_handler(tool_name: str):
 """Create a tool handler function that forwards calls to the gateway."""
 def handler(**kwargs) -> str:
 # --- Tokenize: scan kwargs for PII and replace with tokens ---
 result = _send_gateway_request(
 "tools/call", {"name": tool_name, "arguments": kwargs}
 )
 content = result.get("content", [])
 # --- Detokenize: reverse tokens in content before returning ---
 if content and isinstance(content, list):
 texts = [c.get("text", str(c)) for c in content if isinstance(c, dict)]
 return "\n".join(texts) if texts else json.dumps(result)
 return json.dumps(result)
 return handler

Токенизацию можно добавить в двух местах внутри closure handler. До вызова _send_gateway_request вы сканируете значения kwargs на предмет шаблонов PII и заменяете их обратимыми токенами (см. Guidance for Tokenization to Improve Data Security and Reduce Audit Scope on AWS). После того как _send_gateway_request вернет ответ, вы восстанавливаете токены в содержимом ответа перед возвратом клиенту. Это позволяет держать PII вне backend target и при этом сохранять end-to-end поток данных для агента.

Контроль доступа на уровне инструмента

Вы можете захотеть ограничить, какие инструменты может вызывать конкретный caller, даже если upstream-сервер предоставляет полный каталог. Это можно реализовать, добавив проверку политики в начале handler-функции, создаваемой _make_tool_handler. Прокси уже получает имя инструмента как параметр при создании handler. Перед пересылкой запроса tools/call на upstream-сервер handler оценивает identity вызывающей стороны по отношению к policy доступа. Identity можно извлечь из inbound request headers или MCP session context. Если caller не авторизован для этого инструмента, handler возвращает response с ошибкой, не обращаясь к upstream-серверу. Также можно фильтровать ответ tools/list в функции register_gateway_tools, чтобы показывать только те инструменты, которые соответствуют заданной policy. Так несанкционированные инструменты вообще не появятся в каталоге инструментов клиента.

Очистка ресурсов

Чтобы избежать повторяющихся расходов, удалите созданные ресурсы, если они больше не нужны после тестирования этого решения. AgentCore CLI предоставляет команду destroy, которая удаляет agent и связанные с ним ресурсы. Выполните следующие команды из корня проекта:

1. Удалите agent AgentCore Runtime и его ECR images:
   Копировать код

   agentcore destroy --agent <agent-name> --delete-ecr-repo --force
   

2. Удалите inline IAM policy и execution role:
   Копировать код

   aws iam delete-role-policy --role-name <your-MCPProxy-Server-Role> --policy-name <your-Gateway-Access-Policy>
   aws iam delete-role --role-name <your-MCPProxy-Server-Role>
   

3. Если вы создавали AgentCore Gateway специально для этого walkthrough и он больше не нужен, удалите Gateway и его targets:
   Копировать код

   agentcore gateway delete-mcp-gateway --name <your-Gateway> --force
   

   Замените имя агента, имя роли и имя Gateway на те значения, которые вы использовали при развертывании.

Заключение

В этой статье показано, как построить и развернуть serverless MCP-прокси на Amazon Bedrock AgentCore Runtime, который добавляет пользовательские контроли к MCP-трафику. Прокси динамически обнаруживает инструменты на upstream MCP-сервере при запуске, повторно публикует их как стандартный MCP-сервер и пересылает вызовы инструментов во время работы. Это дает программируемый слой, где можно применять кастомную логику, такую как проверка входных данных, логирование, ограничение скорости или обогащение ответов.

Мы прошли end-to-end workflow с использованием AgentCore Gateway как upstream-сервера и разобрали, как адаптировать прокси для Gateway, настроенных либо на IAM, либо на JWT inbound authorization. Прокси stateless и работает как обычный контейнер на AgentCore Runtime. Его можно подключить к другим MCP-совместимым upstream-серверам, связать несколько upstream endpoint или добавить middleware-логику, специфичную для вашей нагрузки. Полный исходный код, скрипты развертывания и test agent доступны на GitHub.

Чтобы начать, клонируйте репозиторий, настройте endpoint вашего upstream MCP-сервера и запустите автоматизированный скрипт развертывания. Чтобы узнать больше о создании и развертывании агентов в AgentCore и использовании Strands Agents framework, изучите документацию Amazon Bedrock AgentCore и Strands Agents SDK.

Материал — перевод статьи с английского.

Оригинал: Run custom MCP proxies serverless on Amazon Bedrock AgentCore Runtime