S3 MCP-Server auf ECS Fargate

Ein entfernter, OAuth2-authentifizierter MCP-Server, der schreibgeschützte S3-Tools (list_buckets, list_objects, get_bucket_public_access, get_bucket_size) bereitstellt, entworfen, um als ECS-Fargate-Task hinter einem ALB und CloudFront mit Auth0 als Identitätsanbieter zu laufen.

Wie alles zusammenhängt

• CloudFront beendet TLS am Edge und leitet jeden Header (einschließlich Authorization) über einfaches HTTP an ein internes ALB weiter.

• ALB übergibt die Anfrage an den ECS-Fargate-Task auf Port 8080.

• Der Task (server.py) validiert das Bearer-Token gegen Auth0, bevor ein Tool ausgeführt wird, und kommuniziert dann mit S3 unter Verwendung der IAM-Rolle des Tasks — keine statischen AWS-Anmeldeinformationen irgendwo.

• Der Task erreicht sowohl den JWKS-Endpunkt von Auth0 als auch die öffentliche API von S3 über ein NAT-Gateway, da er in privaten Subnetzen läuft und kein S3-VPC-Endpunkt konfiguriert ist.

Der OAuth-Handshake (Login, PKCE-Code-Austausch) findet vollständig zwischen dem MCP-Client (z. B. Claude Desktop) und Auth0 statt — der Server ist nur ganz am Anfang (Ausliefern seines eigenen Discovery-Dokuments) und ganz am Ende (Validieren des resultierenden Tokens) beteiligt. Behalten Sie dies beim Debuggen im Hinterkopf: Ein fehlgeschlagener Login taucht nie in den Logs dieses Servers auf, da der Server nie Teil dieses Austauschs war.

Related MCP server: aws-safe-mcp

Auth0-Einrichtung

Sie benötigen einen Auth0-Tenant (der kostenlose Tarif reicht aus) mit zwei Dingen:

1. Eine API — dies bewirkt, dass Auth0 echte JWT-Zugriffstoken anstelle von undurchsichtigen ausstellt.

   • Dashboard → Applications → APIs → Create API

   • Identifier: Die genaue URL, mit der Clients verbunden werden, z. B. https://your-domain.example.com/sse — dies wird zu AUTH0_AUDIENCE und muss bytegenau mit dem übereinstimmen, was Sie dahinter bereitstellen.

   • Signing-Algorithmus: RS256 (Standard)

2. Eine Anwendung — als welche der MCP-Client sich authentifiziert.

   • Dashboard → Applications → Applications → Create Application

   • Typ: Regular Web Application

   • Setzen Sie unter Settings bei Allowed Callback URLs die Weiterleitungs-URI(s), die Ihr MCP-Client verwendet (für Claude Desktop: https://claude.ai/api/mcp/auth_callback)

   • Notieren Sie sich Domain, Client ID und Client Secret — diese werden zu AUTH0_DOMAIN / AUTH0_CLIENT_ID / dem Client-Secret, das Sie Ihrem MCP-Client geben (der Server selbst benötigt das Secret nie).

3. Autorisieren Sie die Anwendung für die API – dieser Schritt wird leicht übersehen. Das separate Erstellen einer API und einer Anwendung verknüpft diese nicht. Gehen Sie zur API → Reiter Application Access → schalten Sie Ihre Anwendung ein. Wenn Sie dies überspringen, schlägt jeder Autorisierungsversuch mit invalid_request / „Client is not authorized to access resource server“ fehl, bevor der Client jemals eine Anmeldeseite sieht.

Lokaler Test (kein AWS für die Transportschicht erforderlich)

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

Server hört auf http://localhost:8080/sse. /health gibt 200 ok ohne erforderliche Authentifizierung zurück – das ist der Health-Check-Pfad der ALB-Zielgruppe.

Jede andere Route erfordert Authorization: Bearer <token>, wobei das Token ein Auth0-Zugriffstoken (JWT, aud muss AUTH0_AUDIENCE entsprechen) für einen App-Client ist, der mit AUTH0_CLIENT_ID übereinstimmt.

Docker

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

Bereitstellen auf 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 sollte der CloudFront-Domain entsprechen, die CDK gleich erstellen wird, mit angehängtem /sse – Sie werden sie beim allerersten Deployment wahrscheinlich nicht kennen. Stellen Sie einmal bereit, um die DistributionURL-Ausgabe zu erhalten, und stellen Sie dann mit dem tatsächlichen Audience-Wert erneut bereit (dies muss nur einmal passieren; die CloudFront-Domain ist bei nachfolgenden Deployments desselben Stacks stabil).

Anstatt jedes Mal -c-Flags zu übergeben, können Sie sie in eine git-ignorierte Datei infra/cdk.context.json legen:

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

Dinge, die Benutzer beißen

1. ALB-Leerlauf-Timeout. SSE-Verbindungen sind langlebig. Das Standard-Leerlauf-Timeout des ALB (60s) wird sie beenden. Dieser Stack setzt es auf 300 (5 Min.) – erhöhen Sie es weiter, wenn Ihr Client keine regelmäßigen Pings sendet.

2. Health-Check-Pfad. Der Health-Check der Zielgruppe zeigt auf /health, nicht auf /sse – /sse erfordert Authentifizierung und ist eine Streaming-Antwort, beides erwartet der ALB-Health-Checker nicht.

3. Anmeldeinformationen. Der Container setzt niemals AWS-Anmeldeinformationen – boto3 holt sie automatisch über den Container-Anmeldeinformations-Endpunkt aus der IAM-Rolle des Fargate-Tasks. Backen Sie keine Schlüssel in das Image oder die Umgebungsvariablen.

4. Ausgehender Verkehr. Der Task ruft bei der ersten Anfrage Auth0s JWKS über HTTPS ab (cached dann für eine Stunde) und ruft bei jedem Tool-Aufruf die öffentliche API von S3 auf – beides geht über das NAT-Gateway nach außen, da dieser Stack keinen S3-VPC-Gateway-Endpunkt konfiguriert. Stellen Sie sicher, dass das Subnetz des Tasks tatsächlich eine NAT-Route hat, oder fügen Sie einen Gateway-Endpunkt für S3 hinzu (kostenlos und hält diesen Datenverkehr vom öffentlichen Internet fern).

5. Der DNS-Rebinding-Schutz des MCP-SDKs wird dies hinter einer echten Domain stillschweigend zerstören. FastMCPs TransportSecuritySettings standardmäßig mit einer leeren Liste erlaubter Hosts, was jede Anfrage ablehnt, die mit einem echten Host-Header eintrifft (wie Ihre CloudFront-Domain) – selbst nach erfolgreicher Authentifizierung – mit 421 Misdirected Request. Dies geschieht nach Abschluss des OAuth-Flows, sodass es leicht mit einem Auth-Fehler verwechselt werden kann. Dieser Server deaktiviert es in server.py, da Auth0AuthMiddleware bereits jede Route mit Bearer-Token-Authentifizierung abschirmt:

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

Minimale IAM-Task-Rollenrichtlinie (schreibgeschützte Tools oben)

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

Schränken Sie Resource auf spezifische Bucket-ARNs ein, sobald Sie wissen, welche Buckets dieser Agent tatsächlich sehen darf. Wenn Sie später ein Schreib-Tool hinzufügen (z. B. Lifecycle-Richtlinienänderungen), geben Sie ihm eine eigene engere Anweisung, anstatt diese zu erweitern.

MCP-Client-Konfiguration

Richten Sie jeden MCP-Client, der entfernte SSE-Server unterstützt, auf Ihre bereitgestellte URL aus, mit der Client-ID und dem Secret der Auth0-Anwendung aus den Einrichtungsschritten oben:

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

Die genaue Konfigurationsform hängt vom Client ab – Claude Desktop stellt diese als Formularfelder unter seinen Connector-Einstellungen dar, nicht als rohes JSON. In beiden Fällen wird der OAuth-Weiterleitungs-/Token-Austausch vom Client gemäß der MCP-Autorisierungsspezifikation durchgeführt; dieser Server validiert nur das resultierende Bearer-Token bei jeder Anfrage.