Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

WorkSpaces MCP-Server für Anwendungen

Der WorkSpaces Applications MCP-Server ist ein vollständig verwalteter Service, der KI-Agenten MCP-Tools (Model Context Protocol) zur Interaktion mit Desktop-Anwendungen während Streaming-Sitzungen zur Verfügung stellt. Agenten können auf Schaltflächen klicken, Text eingeben, scrollen und Screenshots vom Desktop machen.

-Übersicht

Wenn Sie den Agentenzugriff auf einem Stack aktivieren, können Agenten eine Verbindung zum verwalteten MCP-Server herstellen, um mit Desktop-Anwendungen zu interagieren. Der MCP-Server kümmert sich um die Kommunikation zwischen Ihrem Agenten und der Streaming-Sitzung. Ihr Agent sendet MCP-Tool-Anfragen, und der Server führt sie auf dem Desktop aus.

Der Agentenzugriff unterstützt sowohl nicht domänengebundene als auch domänengebundene Flotten. Die Verbindungsmethode unterscheidet sich je nach Flottenart. Für Flotten, die nicht in eine Domäne eingebunden sind, können Sie auf zwei Arten eine Verbindung herstellen. Bei der ersten Methode geben Sie den Stack und die Benutzer-ID als zwei Header an: und. x-amzn-agentaccess-workspaces-applications-stack x-amzn-agentaccess-workspaces-applications-user-id Der MCP-Server erstellt dann die Streaming-Sitzung für Sie. Im zweiten Fall generieren Sie selbst eine Streaming-URL und übergeben sie als Header. Authentifizieren Sie sich für Flotten, die in eine Domäne eingebunden sind, über den SAML-Verbund. Den Pfad, der zu Ihrer Flotte passt, finden Sie unter. Verbindung zum MCP-Server herstellen

Verbindung zum MCP-Server herstellen

Agenten stellen am folgenden Endpunkt eine Verbindung zum MCP-Server her:

https://agentaccess-mcp.region.api.aws/mcp

Ersetzen Sie es region durch Ihren Regionalcode. Informationen zu den unterstützten Regionen und ihren Endpunkten finden Sie unterWorkSpaces Anwendungen (MCP-Endpunkte).

Der MCP-Server wird in der AWS Cloud gehostet und verwendet Streamable HTTP als Transportprotokoll. Sie müssen keine Serverkomponenten installieren oder warten.

Um einen Agenten zu verbinden, treffen Sie zwei Möglichkeiten: wie der Agent seine Anfragen autorisiert und wie er die Streaming-Sitzung identifiziert.

Autorisierung beantragen

Sie können Anfragen auf zwei Arten autorisieren: durch SigV4-Signatur oder durch OAuth 2.1-Autorisierung. AWS Sign-In

SigV4-Signatur

Um SigV4 zu verwenden, signieren Sie jede Anfrage mit IAM-Anmeldeinformationen mit dem Dienstnamen. agentaccess-mcp Das folgende Python-Beispiel zeigt das allgemeine Verbindungsmuster mitmcp-proxy-for-aws:

from mcp_proxy_for_aws import aws_iam_streamablehttp_client

async with aws_iam_streamablehttp_client(
    endpoint="https://agentaccess-mcp.region.api.aws/mcp",
    aws_service="agentaccess-mcp",
    aws_region="region",
    headers={
        # Fleet-type-specific headers (see the following subsections)
    },
    metadata={
        # Fleet-type-specific metadata (see the following subsections)
    },
) as (read, write, _):
    # Use read/write streams with your MCP client
    ...

Schreiben Sie für andere Sprachen Ihre eigene Sigv4-Signaturlogik für ausgehende MCP-Anfragen oder verwenden Sie eine Bibliothek, die SigV4-Signaturen unterstützt. Weitere Informationen zu finden Sie unter mcp-proxy-for-aws mcp-proxy-for-aws unter. GitHub

OAuth 2.1-Autorisierung

Als Alternative zum Signieren von Anfragen mit IAM-Anmeldeinformationen unterstützt der MCP-Server die OAuth 2.1-Autorisierung auf die gleiche Weise wie der MCP-Server AWS Sign-In. AWS AWS Sign-In fungiert als Autorisierungsserver. Er gibt kurzlebige Zugriffstoken mit begrenztem Gültigkeitsbereich aus. Der MCP-Server akzeptiert diese Token als Inhabertoken. OAuth verwendet Ihre vorhandenen IAM-Identitäten, Berechtigungen und Organisationskontrollen. Wenn Sie einen Agenten autorisieren, kann er in Ihrem Namen auf den MCP-Server zugreifen. Es erhält keine zusätzlichen Berechtigungen. AWS überprüft immer noch jede Anfrage anhand Ihrer IAM-Richtlinien.

OAuth-compatible MCP-Clients — wie Kiro, Claude Code, Cursor, Codex und Gemini — können sich ohne lokale Proxysoftware direkt mit dem MCP-Serverendpunkt verbinden. AWS Sign-In unterstützt zwei Autorisierungsmodelle:

Die OAuth-Autorisierung für den MCP-Server funktioniert genauso wie für den MCP-Server, wobei der AWS MCP-Serverendpunkt () verwendet wird. https://agentaccess-mcp.region.api.aws/mcp Informationen zur Einrichtung, den erforderlichen IAM-Berechtigungen sowie zu den Governance- und Überwachungsoptionen finden Sie unter OAuth 2.1-Authentifizierung für AWS MCP Server im Agent Toolkit for AWS-Benutzerhandbuch und Sign-Inmit OAuth 2.0 im Benutzerhandbuch.AWS Sign-In

Identifizierung der Sitzung

Wie Sie die Streaming-Sitzung identifizieren, hängt von Ihrem Flottentyp ab.

Verbindung zu Flotten herstellen, die nicht in eine Domäne eingebunden sind

Für Flotten, die nicht in eine Domäne eingebunden sind, können Sie auf zwei Arten eine Verbindung herstellen. Geben Sie den Stack und die Benutzer-ID als Header an, und der MCP-Server erstellt die Streaming-Sitzung für Sie. Dies eignet sich für MCP-Clients, die Sie statisch konfigurieren, da ein solcher Client ein festes Headerpaar enthalten kann, aber keine Streaming-URL generieren oder eine ersetzen kann, wenn sie abläuft. Alternativ können Sie selbst eine Streaming-URL generieren und sie als Header übergeben. Verwenden Sie diesen Ansatz, wenn Sie die Kontrolle über die Sitzungserstellung benötigen, z. B. die Festlegung der Gültigkeitsdauer.

Um eine Verbindung mit dem Stack und der Benutzer-ID herzustellen, übergeben Sie bei jeder Anfrage die folgenden Header:

from mcp_proxy_for_aws import aws_iam_streamablehttp_client

# Connect to the MCP server with the stack and user ID
async with aws_iam_streamablehttp_client(
    endpoint="https://agentaccess-mcp.region.api.aws/mcp",
    aws_service="agentaccess-mcp",
    aws_region="region",
    headers={
        "x-amzn-agentaccess-workspaces-applications-stack": "stack-name-or-arn",
        "x-amzn-agentaccess-workspaces-applications-user-id": "user-id",
    },
) as (read, write, _):
    ...

Um stattdessen eine Verbindung mit einer Streaming-URL herzustellen, generieren Sie eine mithilfe der CreateStreamingURL API und übergeben Sie sie bei jeder Anfrage als x-amzn-agentaccess-streaming-session-url Header. Es sind keine agentenspezifischen Parameter erforderlich. Das Agentenverhalten wird durch die Agentenzugriffskonfiguration des Stacks bestimmt.

import boto3
from mcp_proxy_for_aws import aws_iam_streamablehttp_client

# Generate streaming URL
appstream = boto3.client("appstream", region_name="region")
response = appstream.create_streaming_url(
    StackName="stack-name",
    FleetName="fleet-name",
    UserId="user-id",
)
streaming_url = response["StreamingURL"]

# Connect to MCP server
async with aws_iam_streamablehttp_client(
    endpoint="https://agentaccess-mcp.region.api.aws/mcp",
    aws_service="agentaccess-mcp",
    aws_region="region",
    headers={
        "x-amzn-agentaccess-streaming-session-url": streaming_url,
    },
) as (read, write, _):
    ...

Weitere Informationen zur CreateStreamingURL API finden Sie unter CreateStreamingURL in der Amazon WorkSpaces Applications 2.0 API-Referenz.

Verbindung mit Flotten herstellen, die einer Domäne angehören

Wenn Agenten auf in eine Domäne eingebundene Streaming-Instances zugreifen, muss die Verbindung über einen SAML-Anbieter gebündelt werden. Diese Anforderung gilt sowohl für herkömmliche Sitzungen als auch für Agentensitzungen. Für Agentensitzungen Certificate-Based Authentifizierung ist dies erforderlich.

Da in eine Domäne eingebundene Streaming-Instances Zugriff über SAML erfordern, muss Ihr MCP-Client anstelle einer Streaming-URL eine signierte SAML-Assertion bereitstellen. Kodierte SAML-Assertionen überschreiten die Größenbeschränkungen für HTTP-Header. Um dies zu vermeiden, verwenden Sie das Feld inmetadata: mcp-proxy-for-aws

from mcp_proxy_for_aws import aws_iam_streamablehttp_client

# saml_response: your signed, base64-encoded SAML assertion
# stack_arn: the ARN of the AppStream stack for the AD user

async with aws_iam_streamablehttp_client(
    endpoint="https://agentaccess-mcp.region.api.aws/mcp",
    aws_service="agentaccess-mcp",
    aws_region="region",
    metadata={
        "saml_response": saml_response,
        "stack_arn": stack_arn,
    },
) as (read, write, _):
    ...

Weitere Informationen zur Einrichtung eines SAML-Verbunds mit WorkSpaces Anwendungen finden Sie unter Setting up SAML im Amazon WorkSpaces Applications Administration Guide. Weitere Informationen und ein vollständiges funktionierendes Beispiel finden Sie im Repository sample-code-for-workspaces-agent-access unter Samples on. AWS GitHub

Verbindungsmodi

Sie können steuern, wie Ihr Agent darauf wartet, dass die Desktop-Sitzung verfügbar wird, indem Sie den x-amzn-agentaccess-connect-mode Header für Ihre MCP-Anfragen festlegen.

Die folgenden Modi sind verfügbar:

Verwenden Sie den POLLING-Modus, wenn Sie möchten, dass Ihr Agent andere Aufgaben ausführt, während er auf die Desktop-Verbindung wartet, oder wenn Sie mehr Kontrolle über das Verhalten bei Verbindungstimeouts benötigen.

Das folgende Beispiel zeigt, wie der POLLING-Modus verwendet wird:

# Pass the header when creating the MCP connection
headers = {
    "x-amzn-agentaccess-streaming-session-url": streaming_url,  # non-domain-joined fleets
    "x-amzn-agentaccess-connect-mode": "POLLING",
}

# After initialize, tools/list returns immediately with connection_status
tools = await session.list_tools()
# tools = [connection_status]

# Poll connection_status until the desktop is ready
while True:
    result = await session.call_tool("connection_status", {})
    status = json.loads(result.content[0].text)
    if status["state"] == "CONNECTED":
        break
    time.sleep(2)

# Now tools/list returns the full set (screenshot, left_click, type_text, etc.)
tools = await session.list_tools()

Bereinigung der Sitzung

Sie können steuern, ob die Streaming-Sitzung abgelaufen ist, wenn Ihr Agent die Verbindung beendet, indem Sie den x-amzn-agentaccess-expire-streaming-session-on-delete Header für Ihre MCP-Anfragen festlegen. Die folgenden Werte sind verfügbar:

Verfügbare Tools

Der MCP-Server bietet die folgenden Tools. Agenten verwenden sie, um während einer Streaming-Sitzung mit dem Desktop zu interagieren. Alle Toolnamen verwenden das agentaccess___ Präfix.

Werkzeuge für die Maus

Werkzeuge für die Tastatur

Tools für den Bildschirm

Anwendungstools

Tools für Sitzungen

Weiterleitung von MCP-Tools

Mit der MCP-Tool-Weiterleitung können Agenten direkt mit Anwendungen und dem Betriebssystem arbeiten. Sie tätigen direkte MCP-Anrufe, anstatt Computertools zu verwenden. Wenn Sie die Tool-Weiterleitung aktivieren, sendet der MCP-Server Ihrem Agenten die in der WorkSpaces Anwendungssitzung eingerichteten Tools.

Tool-Weiterleitung einrichten

So richten Sie die MCP-Tool-Weiterleitung ein:

Überlegungen zur Weiterleitung von MCP-Tools

Beachten Sie bei der Konfiguration der MCP-Tool-Weiterleitung die folgenden Überlegungen:

Wie weitergeleitete Tools dem Agenten angezeigt werden

Um Kollisionen zwischen Servern zu vermeiden, benennt der MCP-Server jedes weitergeleitete Tool in der Toolliste des Agenten nach dem folgenden Muster um:

forwarded___server-name___original-tool-name

Das server-name ist der Schlüssel aus Ihrer Konfigurationsdatei. Ein get_forecast Tool vom weather Server wird beispielsweise als aufgeführtforwarded___weather___get_forecast. Wenn der Agent den weitergeleiteten Namen aufruft, leitet der MCP-Server die Anfrage an das ursprüngliche Tool auf dem Server weiter, der Eigentümer ist. Agentencode, der mit den Namen der Tools übereinstimmt, muss dieses Präfix erwarten.

IAM-Berechtigungen für die Weiterleitung von Tools

Die IAM-Aktion zum Aufrufen weitergeleiteter Tools ist. CallForwardedTool Um den Zugriff auf bestimmte Stacks zu beschränken, verwenden Sie den StackArn Bedingungsschlüssel:

{
  "Action": "agentaccess-mcp:*",
  "Resource": "*",
  "Condition": {
    "ArnLike": {
      "agentaccess-mcp:StackArn": "arn:aws:appstream:region:account-id:stack/stack-name"
    }
  }
}

Kompatible Frameworks

Sie können von jedem MCP-compatible Agent-Framework aus, das Streamable HTTP- und Sigv4-Signaturen unterstützt, eine Verbindung zum WorkSpaces Applications MCP-Server herstellen. Die folgenden Frameworks wurden getestet:

Überwachen

Sie können die Agentenaktivität mithilfe der folgenden Dienste überwachen:

Erste Schritte

Informationen zu den ersten Schritten mit dem WorkSpaces Applications MCP-Server finden Sie unter. Beginnen Sie damit, Agenten Zugriff auf Anwendungen zu WorkSpaces gewähren