Сервер S3 MCP на ECS Fargate

Удаленный MCP-сервер с аутентификацией через OAuth2, предоставляющий инструменты S3 только для чтения (list_buckets, list_objects, get_bucket_public_access, get_bucket_size), предназначенный для работы в качестве задачи ECS Fargate за ALB и CloudFront, с Auth0 в качестве провайдера удостоверений.

Как это работает

• CloudFront завершает TLS на периметре и передает все заголовки (включая Authorization) на внутренний ALB через обычный HTTP.

• ALB передает запрос задаче ECS Fargate на порт 8080.

• Задача (server.py) проверяет Bearer-токен в Auth0 перед выполнением любого инструмента, затем общается с S3, используя IAM-роль задачи — никаких статических учетных данных AWS.

• Задача обращается как к конечной точке JWKS Auth0, так и к публичному API S3 через NAT Gateway, поскольку она работает в частных подсетях без настроенной конечной точки VPC для S3.

Рукопожатие OAuth (вход, обмен кодом PKCE) происходит целиком между MCP-клиентом (например, Claude Desktop) и Auth0 — сервер участвует только в самом начале (предоставляя свой собственный документ обнаружения) и в самом конце (проверяя полученный токен). Имейте это в виду при отладке: неудачный вход никогда не отображается в логах этого сервера, потому что сервер никогда не был частью этого обмена.

Related MCP server: aws-safe-mcp

Настройка Auth0

Вам нужен арендатор Auth0 (бесплатного тарифа достаточно) с двумя вещами внутри:

1. API — это заставляет Auth0 выпускать настоящие JWT-токены доступа вместо непрозрачных.

   • Панель управления → Applications → APIs → Create API

   • Identifier: точный URL, к которому будут подключаться клиенты, напр. https://your-domain.example.com/sse — это станет AUTH0_AUDIENCE и должно совпадать байт-в-байт с тем, что вы развернете.

   • Алгоритм подписи: RS256 (по умолчанию)

2. Приложение — то, под чем аутентифицируется MCP-клиент.

   • Панель управления → Applications → Applications → Create Application

   • Тип: Regular Web Application

   • В Settings установите Allowed Callback URLs на тот URL(ы) перенаправления, который использует ваш MCP-клиент (для Claude Desktop: https://claude.ai/api/mcp/auth_callback)

   • Запишите Domain, Client ID и Client Secret — они станут AUTH0_DOMAIN / AUTH0_CLIENT_ID / секретом клиента, который вы дадите вашему MCP-клиенту (самому серверу секрет никогда не нужен).

3. Авторизуйте Приложение для API — этот шаг легко пропустить. Создание API и Приложения по отдельности не связывает их. Перейдите на вкладку API → Application Access → включите ваше Приложение. Пропустите это, и любая попытка авторизации завершится ошибкой invalid_request / "Client is not authorized to access resource server" еще до того, как клиент увидит страницу входа.

Локальное тестирование (AWS не требуется для транспортного уровня)

cp .env.example .env
# edit .env with your Auth0 tenant details if you want to test auth locally
pip install -r requirements.txt
python server.py

Сервер слушает на http://localhost:8080/sse. /health возвращает 200 ok без требования аутентификации — это путь проверки работоспособности целевой группы ALB.

Все остальные маршруты требуют Authorization: Bearer <token>, где токен является access token от Auth0 (JWT, aud соответствует AUTH0_AUDIENCE) для клиента приложения, соответствующего AUTH0_CLIENT_ID.

Docker

docker build -t s3-mcp-server .
docker run -p 8080:8080 --env-file .env s3-mcp-server

Развертывание в Fargate

cd infra
pip install -r requirements.txt   # into a venv
cdk bootstrap   # first time only, per account/region
cdk deploy \
  -c auth0_domain=your-tenant.us.auth0.com \
  -c auth0_client_id=your-application-client-id \
  -c auth0_audience=https://your-domain.example.com/sse

auth0_audience должен соответствовать домену CloudFront, который CDK собирается создать, с добавленным /sse — вы, скорее всего, не будете знать его при самом первом развертывании. Разверните один раз, чтобы получить вывод DistributionURL, затем повторно разверните с реальным значением audience (это нужно сделать всего один раз; домен CloudFront стабилен при последующих развертываниях того же стека).

Вместо передачи флагов -c каждый раз, вы можете поместить их в игнорируемый git файл infra/cdk.context.json:

{
  "auth0_domain": "your-tenant.us.auth0.com",
  "auth0_client_id": "your-application-client-id",
  "auth0_audience": "https://your-domain.example.com/sse"
}

Что обычно доставляет проблемы

1. Тайм-аут простоя ALB. SSE-соединения долгоживущие. Тайм-аут простоя ALB по умолчанию (60с) разорвет их. Этот стек устанавливает его в 300 (5 мин) — увеличьте его, если ваш клиент не отправляет периодические пинги.

2. Путь проверки работоспособности. Проверка работоспособности целевой группы указывает на /health, а не на /sse — /sse требует аутентификации и является потоковым ответом, ни того, ни другого проверщик работоспособности ALB не ожидает.

3. Учетные данные. Контейнер никогда не устанавливает учетные данные AWS — boto3 получает их автоматически из IAM-роли задачи Fargate через конечную точку учетных данных контейнера. Не встраивайте ключи в образ или переменные окружения.

4. Исходящий трафик. Задача получает JWKS Auth0 через HTTPS при первом запросе (затем кэширует на час) и вызывает публичный API S3 для каждого вызова инструмента — оба проходят через NAT Gateway, так как этот стек не настраивает конечную точку VPC Gateway для S3. Убедитесь, что у подсети задачи действительно есть маршрут через NAT, или добавьте Gateway Endpoint для S3 (бесплатно и убирает этот трафик из публичного интернета).

5. Защита MCP SDK от повторной привязки DNS незаметно сломает это за любым реальным доменом. TransportSecuritySettings у FastMCP по умолчанию имеет пустой список разрешенных хостов, что отклоняет каждый запрос, поступающий с реальным заголовком Host (например, вашим доменом CloudFront) — даже после успешной аутентификации — с 421 Misdirected Request. Это происходит после завершения потока OAuth, поэтому его легко принять за ошибку аутентификации. Этот сервер отключает это в server.py, так как Auth0AuthMiddleware уже блокирует все маршруты аутентификацией по Bearer-токену:

   mcp = FastMCP(
       "s3-mcp-server",
       transport_security=TransportSecuritySettings(enable_dns_rebinding_protection=False),
   )

Минимальная политика IAM-роли задачи (только инструменты для чтения выше)

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "S3ReadOnly",
      "Effect": "Allow",
      "Action": [
        "s3:ListAllMyBuckets",
        "s3:ListBucket",
        "s3:GetBucketAcl",
        "s3:GetBucketPolicyStatus",
        "s3:GetBucketPolicy"
      ],
      "Resource": "*"
    }
  ]
}

Сузьте область Resource до конкретных ARN корзин, как только вы узнаете, какие корзины этому агенту должно быть разрешено видеть. Если вы позже добавите инструмент для записи (например, изменения политики жизненного цикла), дайте ему свой собственный более узкий оператор, а не расширяйте этот.

Конфигурация MCP-клиента

Направьте любой MCP-клиент, поддерживающий удаленные SSE-серверы, на ваш развернутый URL, указав Client ID и Secret приложения Auth0 из шагов настройки выше:

{
  "mcpServers": {
    "s3": {
      "url": "https://your-domain.example.com/sse",
      "oauth_client_id": "your-application-client-id",
      "oauth_client_secret": "your-application-client-secret"
    }
  }
}

Точная форма конфигурации зависит от клиента — Claude Desktop отображает их в виде полей формы в настройках Connectors, а не в виде сырого JSON. В любом случае, обмен OAuth-перенаправления/токена обрабатывается клиентом в соответствии со спецификацией авторизации MCP; этот сервер только проверяет полученный Bearer-токен при каждом запросе.