기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

WorkSpaces 애플리케이션 MCP 서버

WorkSpaces 애플리케이션 MCP 서버는 AI 에이전트에게 스트리밍 세션 중에 데스크톱 애플리케이션과 상호 작용할 수 있는 모델 컨텍스트 프로토콜(MCP) 도구를 제공하는 완전관리형 서비스입니다. 에이전트는 버튼을 클릭하고, 텍스트를 입력하고, 스크롤하고, 데스크톱의 스크린샷을 캡처할 수 있습니다.

개요

스택에서 에이전트 액세스를 활성화하면 에이전트가 관리형 MCP 서버에 연결하여 데스크톱 애플리케이션과 상호 작용할 수 있습니다. MCP 서버는 에이전트와 스트리밍 세션 간의 통신을 처리합니다. 에이전트가 MCP 도구 요청을 전송하면 서버가 데스크톱에서 요청을 실행합니다.

MCP 서버는 AWS 클라우드에서 호스팅됩니다. 서버 구성 요소를 설치하거나 유지 관리할 필요가 없습니다. 서버는 스트리밍 가능한 HTTP를 전송 프로토콜로 사용합니다.

에이전트 액세스는 도메인에 non-domain-joined 플릿과 도메인에 조인된 플릿을 모두 지원합니다. 연결 방법은 플릿 유형에 따라 다릅니다. Non-domain-joined 플릿은 스트리밍 URL로 세션을 인증하는 반면, 도메인에 조인된 플릿은 SAML 페더레이션을 통해 인증합니다. 플릿과 일치하는 경로는 섹션을 참조하세요MCP 서버에 연결.

MCP 서버에 연결

에이전트는 다음 엔드포인트에서 MCP 서버에 연결합니다.

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

MCP 서버는 AWS 클라우드에서 호스팅되며 스트리밍 가능한 HTTP를 전송 프로토콜로 사용합니다. 서버 구성 요소를 설치하거나 유지 관리할 필요가 없습니다.

모든 요청은 서비스 이름이 인 IAM 자격 증명을 사용하여 SigV4-signed되어야 합니다agentaccess-mcp. 다음 Python 예제는를 사용하는 일반적인 연결 패턴을 보여줍니다mcp-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
    ...

다른 언어의 경우 발신 MCP 요청에 대한 자체 SigV4 서명 로직을 작성하거나 SigV4 서명을 지원하는 라이브러리를 사용합니다. 에 대한 자세한 내용은 GitHub의 mcp-proxy-for-aws를 mcp-proxy-for-aws참조하세요.

스트리밍 세션을 인증하는 방법은 플릿 유형에 따라 다릅니다.

non-domain-joined 플릿에 연결

non-domain-joined 플릿의 경우 CreateStreamingURL API를 사용하여 스트리밍 URL을 생성하고 모든 요청에서 X-Amzn-AgentAccess-Streaming-Session-Url 헤더로 전달합니다. 에이전트별 파라미터는 필요하지 않습니다. 에이전트 동작은 스택의 에이전트 액세스 구성에 따라 결정됩니다.

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, _):
    ...

CreateStreamingURL API에 대한 자세한 내용은 Amazon WorkSpaces Applications 2.0 API 참조의 CreateStreamingURL을 참조하세요. Amazon WorkSpaces

도메인에 조인된 플릿에 연결

에이전트가 도메인에 조인된 스트리밍 인스턴스에 액세스하는 경우 SAML 공급자를 통해 연결을 페더레이션해야 합니다. 이 요구 사항은 표준 세션과 에이전트 세션 모두에 적용됩니다. 표준 세션을 사용하면 사용자가 암호를 수동으로 입력하거나 원활한 로그인 경험을 위해 인증서 기반 인증을 사용할 수 있습니다. 에이전트 세션의 경우 인증서 기반 인증이 필요합니다.

도메인에 조인된 스트리밍 인스턴스는 SAML을 통해 액세스해야 하므로 MCP 클라이언트는 스트리밍 URL 대신 서명된 SAML 어설션을 제공해야 합니다. 인코딩된 SAML 어설션이 HTTP 헤더 크기 제한을 초과합니다. 이를 방지하려면의 metadata 필드를 사용합니다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, _):
    ...

WorkSpaces 애플리케이션을 사용한 SAML 페더레이션 설정에 대한 자세한 내용은 Amazon WorkSpaces 애플리케이션 관리 안내서의 SAML 설정을 참조하세요. Amazon WorkSpaces 자세한 내용과 전체 작업 예제는 GitHub의 샘플에서 sample-code-for-workspaces-agent-access 리포지토리를 참조하세요. AWS

연결 모드

MCP 요청에 X-Amzn-AgentAccess-Connect-Mode 헤더를 설정하여 에이전트가 데스크톱 세션을 사용할 수 있을 때까지 기다리는 방법을 제어할 수 있습니다.

다음 모드를 사용할 수 있습니다.

데스크톱 연결을 기다리는 동안 에이전트가 다른 작업을 수행하도록 하거나 연결 제한 시간 동작을 더 잘 제어해야 하는 경우 POLLING 모드를 사용합니다.

다음 예제에서는 POLLING 모드를 사용하는 방법을 보여줍니다.

# 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()

세션 정리

MCP 요청에 X-Amzn-AgentAccess-Expire-Streaming-Session-On-Delete 헤더를 설정하여 에이전트가 연결을 종료할 때 스트리밍 세션이 만료되는지 여부를 제어할 수 있습니다. 다음 값을 사용할 수 있습니다.

사용 가능한 도구

MCP 서버는 에이전트가 스트리밍 세션 중에 데스크톱과 상호 작용할 수 있도록 다음과 같은 도구를 제공합니다. 모든 도구 이름은 agentaccess___ 접두사를 사용합니다.

마우스 도구

키보드 도구

화면 도구

MCP 도구 전달

MCP 도구 전달을 사용하면 에이전트가 컴퓨터 사용 도구를 사용하는 대신 직접 MCP 호출을 통해 애플리케이션 및 데스크톱 운영 체제와 상호 작용할 수 있습니다. 도구 전달을 활성화하면 MCP 서버가 WorkSpaces 애플리케이션 세션에 구성된 도구를 에이전트에게 전달합니다.

도구 전달 설정

MCP 도구 전달을 설정하려면:

도구 전달을 위한 IAM 권한

전달된 도구를 호출하기 위한 IAM 작업은 입니다CallForwardedTool. StackArn 조건 키를 사용하여 특정 스택에 대한 액세스 범위를 지정할 수 있습니다.

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

호환 가능한 프레임워크

스트리밍 가능한 HTTP 및 SigV4 서명을 지원하는 모든 MCP 호환 에이전트 프레임워크에서 WorkSpaces 애플리케이션 MCP 서버에 연결할 수 있습니다. 다음 프레임워크가 테스트되었습니다.

모니터링

다음 서비스를 통해 에이전트 활동을 모니터링할 수 있습니다.

시작하기

WorkSpaces Applications MCP 서버를 시작하려면 섹션을 참조하세요에이전트에게 WorkSpaces 애플리케이션에 대한 액세스 권한 제공 시작하기.