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

# WorkSpaces 애플리케이션 MCP 서버
<a name="agent-access-mcp-server"></a>

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

## 개요
<a name="agent-access-mcp-server-overview"></a>

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

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

## MCP 서버에 연결
<a name="agent-access-mcp-server-endpoint"></a>

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

```
https://agentaccess-mcp.{{region}}.api.aws/mcp
```

각 요청에는 다음이 포함되어야 합니다.
+ **SigV4 서명** - 모든 요청은 서비스 이름이 인 IAM 자격 증명을 사용하여 서명해야 합니다`agentaccess-mcp`.
+ **스트리밍 URL 헤더** - `CreateStreamingURL` API의 스트리밍 URL은 모든 요청에서 `X-Amzn-AgentAccess-Streaming-Session-Url` 헤더로 전달되어야 합니다.

다음 Python 예제에서는를 사용하여 연결하는 방법을 보여줍니다`mcp-proxy-for-aws`.

```
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,
    },
)
```

다른 언어의 경우 발신 MCP 요청에 대한 자체 서명 로직을 작성하거나 SigV4 서명을 지원하는 사용 가능한 라이브러리를 찾아야 합니다.

에 대한 자세한 내용은 GitHub의 [mcp-proxy-for-aws](https://github.com/aws/mcp-proxy-for-aws)를 `mcp-proxy-for-aws`참조하세요.

## 사용 가능한 도구
<a name="agent-access-mcp-server-tools"></a>

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

### 마우스 도구
<a name="agent-access-mcp-tools-mouse"></a>

`left_click`  
지정된 좌표에서 왼쪽 클릭을 수행합니다.  
파라미터: `x` (필수), `y` (필수), `modifiers` (선택 사항, 예: `ctrl` 또는 `ctrl+shift`).

`double_click`  
지정된 좌표를 두 번 클릭합니다.  
파라미터: `x` (필수), `y` (필수), `modifiers` (선택 사항).

`triple_click`  
지정된 좌표에서 세 번 클릭합니다.  
파라미터: `x` (필수), `y` (필수), `modifiers` (선택 사항).

`right_click`  
주어진 좌표에서 마우스 오른쪽 버튼을 클릭합니다.  
파라미터: `x` (필수), `y` (필수), `modifiers` (선택 사항).

`middle_click`  
지정된 좌표에서 중간 클릭을 수행합니다.  
파라미터: `x` (필수), `y` (필수), `modifiers` (선택 사항).

`left_click_drag`  
시작 좌표에서 끝 좌표로 왼쪽 클릭 드래그를 수행합니다.  
파라미터: `start_x` (필수), `start_y` (필수), `end_x` (필수), `end_y` (필수).

`left_mouse_down`  
주어진 좌표에서 마우스 왼쪽 버튼을 길게 누릅니다.  
파라미터: `x` (필수), `y` (필수), `modifiers` (선택 사항).

`left_mouse_up`  
주어진 좌표에서 마우스 왼쪽 버튼을 놓습니다.  
파라미터: `x` (필수), `y` (필수), `modifiers` (선택 사항).

`move_pointer`  
포인터를 지정된 좌표로 이동합니다.  
파라미터: `x` (필수), `y` (필수).

`scroll`  
주어진 좌표에서 마우스 휠을 스크롤합니다.  
파라미터: `x` (필수), `y` (필수), `scroll_direction` (필수 - `Up`, `Down``Left`, 또는 `Right`), `scroll_amount` (필수 - 틱 단위, 여기서 120 틱은 1개의 휠 홈과 동일), `modifiers` (선택 사항).

### 키보드 도구
<a name="agent-access-mcp-tools-keyboard"></a>

`type_text`  
각 캐릭터에 대한 키보드 이벤트를 시뮬레이션하여 텍스트를 입력합니다.  
파라미터: `text` (필수 - 최대 10,000자).

`key`  
키 또는 키 조합을 누릅니다.  
파라미터: `keys` (필수 - `+`, 또는와 같이 로 조인된 단일 키 `a` `ctrl+c`또는 조합`ctrl+shift+s`).

`hold_key`  
지정된 기간 동안 키 또는 키 조합을 유지합니다.  
파라미터: `keys` (필수), `duration` (필수 — 1\~30초).

### 화면 도구
<a name="agent-access-mcp-tools-screen"></a>

`screenshot`  
데스크톱의 스크린샷을 캡처합니다. 반환된 이미지 차원은 모든 마우스 도구의 좌표 공간을 정의합니다.  
파라미터: `include_cursor` (선택 사항 - 기본값은 `false`)

## 호환 가능한 프레임워크
<a name="agent-access-mcp-server-frameworks"></a>

스트리밍 가능한 HTTP 및 SigV4 서명을 지원하는 모든 MCP 호환 에이전트 프레임워크에서 WorkSpaces 애플리케이션 MCP 서버에 연결할 수 있습니다. 다음 프레임워크가 테스트되었습니다.
+ [Strands Agents SDK](https://strandsagents.com/docs/user-guide/concepts/tools/mcp-tools/) - 기본 MCP 클라이언트 지원을 제공합니다.
+ [mcp-proxy-for-aws](https://github.com/aws/mcp-proxy-for-aws) - Python에서 MCP 요청에 대한 SigV4 서명을 처리하는 경량 전송입니다.

## 모니터링
<a name="agent-access-mcp-server-monitoring"></a>

다음 서비스를 통해 에이전트 활동을 모니터링할 수 있습니다.
+ **AWS CloudTrail** - 에이전트 세션 이벤트는 CloudTrail에 로깅됩니다. 에이전트가 연결되는 시간, 에이전트가 사용하는 도구 및 세션이 종료되는 시간을 볼 수 있습니다. 도구 호출은 데이터 이벤트이며 데이터 이벤트를 로깅하도록 추적을 설정해야 합니다. 자세한 내용은 *CloudTrail 사용 설명서*의 [데이터 이벤트 로깅](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html)을 참조하세요.
+ **CloudWatch** - 에이전트 세션의 운영 지표는 CloudWatch에서 사용할 수 있습니다.
+ **Amazon S3** - 스크린샷 스토리지를 구성하면 에이전트 세션 중에 캡처된 스크린샷을 지정한 Amazon S3 버킷에서 사용할 수 있습니다. 스크린샷은 다음 키 형식으로 저장됩니다.

  ```
  agentaccess/screenshots/year={{YYYY}}/month={{MM}}/day={{DD}}/{{session-id}}/{{timestamp}}.png
  ```

  경로의 UUID는 WorkSpaces 애플리케이션 스트리밍 세션 ID입니다.

## 시작하기
<a name="agent-access-mcp-server-get-started"></a>

WorkSpaces Applications MCP 서버를 시작하려면 섹션을 참조하세요[에이전트에게 WorkSpaces 애플리케이션에 대한 액세스 권한 제공 시작하기](getting-started-agent-access.md).