DevOps Agent 원격 서버에 연결

AWS DevOps Agent는 모델 컨텍스트 프로토콜(MCP) 및 Agent-to-Agent(A2A) 프로토콜을 위한 전용 원격 서버를 제공합니다. 이러한 서버를 사용하여 IDE, CLI 또는 사용자 지정 에이전트 통합을 에이전트 스페이스에 연결합니다.

지원되는 프로토콜

• MCP(모델 컨텍스트 프로토콜) - Kiro, Claude Code, Cursor 및 기타 MCP 호환 도구와 같은 IDE 및 CLI 클라이언트를 연결합니다.

• A2A(Agent-to-Agent) v1.0 - agent-to-agent 통신을 위해 자율 에이전트를 연결합니다.

엔드포인트

원격 서버는 리전 URL에서 사용할 수 있습니다.

https://connect.aidevops.{region}.api.aws

프로토콜	경로	방법
MCP	/mcp	POST
A2A	/a2a/*	POST
A2A 에이전트 카드	/.well-known/agent-card.json	GET

사용 가능한 리전 목록은 섹션을 참조하세요지원되는 리전:.

Authentication

MCP 및 A2A 엔드포인트 모두에 대해 두 가지 인증 방법을 사용할 수 있습니다.

• 액세스 토큰(베어러) - 하나의 에이전트 공간으로 범위가 지정된 단일 토큰입니다. 개별 사용을 위한 가장 간단한 설정입니다.

• AWS SigV4 – AWS 자격 증명 기반 인증. 여러 에이전트 스페이스를 지원하고 기존 AWS 자격 증명 거버넌스와 통합됩니다. 자격 AWS 증명을 사용하여 요청에 서명하는 로컬 프록시인 mcp-proxy-for-aws에서 자동으로 처리합니다.

액세스 토큰 생성

사전 조건

• 에이전트 스페이스에서 액세스 토큰 기능을 활성화해야 합니다.

• 액세스 토큰(aidevops:CreateAccessToken, aidevops:RevokeAccessToken, )을 관리하려면 IAM 권한이 있어야 합니다aidevops:RotateAccessToken. 전체 목록은 DevOps 에이전트 IAM 권한 단원을 참조하십시오.

액세스 토큰 활성화

1. AWS Management Console에 로그인하고 AWS DevOps 에이전트 콘솔을 엽니다.

2. 에이전트 스페이스를 선택합니다.

3. 구성 탭을 선택합니다.

4. 액세스 토큰 섹션에서 활성화를 선택합니다.

5. 작업을 확인합니다.

토큰 생성

1. 에이전트 스페이스의 DevOps 에이전트 웹 앱을 열고 탐색 메뉴에서 설정을 선택한 다음 토큰 액세스를 선택합니다.

2. 토큰 생성을 선택합니다.

3. 토큰 이름을 입력하세요.

4. 범위를 선택합니다.

   • read - 조사, 추천, 채팅 및 에이전트 스페이스 리소스를 봅니다.

   • operate - 전체 액세스. 의 모든 항목과 메시지 전송read, 채팅 생성, 백로그 작업 및 권장 사항 관리가 포함됩니다.

5. 클라이언트 유형을 선택합니다.

   • human - IDE 및 CLI 사용(Kiro, Claude Code, Cursor 및 기타 대화형 도구).

   • agent - 자율 A2A 통합 및 프로그래밍 에이전트용.

6. 만료(1~60일)를 설정합니다.

7. 토큰 값을 복사하여 AWS Secrets Manager와 같은 안전하고 안전한 위치에 저장합니다. 다시 검색할 수 없습니다.

토큰을 생성한 후 웹 앱에는 클라이언트에 직접 복사할 수 있는 구성 예제가 표시됩니다.

Kiro와 연결

Kiro 사용자의 경우 IDE 또는 Kiro Powers 마켓플레이스에서 전용 AWS DevOps 에이전트 전원을 사용할 수 있습니다.

1단계: 전원 설치

Powers Marketplace에서 aws-devops-agent 전원을 설치합니다.

2단계: 환경 변수 설정

다음 환경 변수를 설정하여 연결을 구성합니다.

DEVOPS_AGENT_TOKEN=<your-access-token>
DEVOPS_AGENT_REGION=<your-agent-space-region>

3단계: Kiro에서 변수 승인

설정 > MCP 승인 Env Vars로 이동하여 DEVOPS_AGENT_TOKEN 및를 승인합니다DEVOPS_AGENT_REGION. Kiro는 환경 변수가 승인될 때까지 MCP 서버에 환경 변수를 전달하지 않습니다.

4단계: Kiro 다시 시작

Kiro를 다시 시작하여 변경 사항을 적용합니다.

Kiro 전원은 원격 서버 엔드포인트를 사용할 수 없을 때 직접 AWS API 액세스를 제공하는 폴백aws-mcp으로를 포함합니다.

Claude Code로 연결

Claude 코드 사용자의 경우 AWS DevOps 에이전트는 aws-agents-for-devsecops Claude 플러그인에서 사용할 수 있으며,이 플러그인은 AWS DevOps 에이전트 및 AWS 보안 에이전트 기능을 모두 Claude로 가져옵니다. Claude 플러그인 또는 소스 리포지토리에서 설치합니다.

1. aws-agents-for-devsecops 플러그인을 설치합니다.

2. /aws-agents-for-devsecops:setup-devops-agent 명령을 실행하여 연결을 구성합니다.

다른 MCP 클라이언트와 연결

MCP 호환 클라이언트의 경우 다음을 사용하여 서버를 구성합니다.

• URL - https://connect.aidevops.{region}.api.aws/mcp

• 권한 부여 헤더 - Bearer <your-token>

• 제한 시간 - 최소 120초(초기 응답에는 5~30초가 걸릴 수 있으며 진행 중인 채팅 세션에는 시간이 더 오래 걸릴 수 있음)

전용 전원 또는 플러그인을 사용하는 대신 연결을 수동으로 구성하려는 경우이 구성은 Kiro 및 Claude Code에서도 작동합니다.

MCP 구성의 예:

{
  "mcpServers": {
    "aws-devops-agent": {
      "url": "https://connect.aidevops.{region}.api.aws/mcp",
      "headers": {
        "Authorization": "Bearer <your-access-token>"
      }
    }
  }
}

{region}를 에이전트 스페이스의 리전(예: us-east-1)<your-access-token>으로 바꾸고를 토큰 값으로 바꿉니다.

SigV4 인증 사용

SigV4 인증은 액세스 토큰 대신 자격 AWS 증명을 사용합니다. Kiro power 및 Claude Code 플러그인에는 로컬 AWS 자격 증명을 사용하여 요청에 서명mcp-proxy-for-aws하는를 통한 기본 제공 SigV4 지원이 포함되어 있습니다.

SigV4를 사용하는 경우

• 액세스 토큰이 구성되지 않았거나 실패(만료됨, 유효하지 않음)할 때 폴백으로 사용됩니다.

• 여러 에이전트 스페이스가 있고 도구 호출agent_space_id당 로 라우팅해야 하는 경우의 기본 인증입니다.

• 사용자 선택 - Claude Code에서 설정 스킬을 실행하여 베어러 토큰에서 SigV4 인증으로 전환합니다.

사전 조건

• AWS 환경에서 사용 가능한 자격 증명(SSO, 환경 변수 또는 자격 증명 파일을 통해).

• 자격 증명에는 AWS DevOps 에이전트 작업을 호출할 수 있는 권한이 있어야 합니다. 필요한 권한에 대해서는 DevOps 에이전트 IAM 권한을 참조하세요.

• uvx 설치됨(프록시가를 통해 실행됨uvx mcp-proxy-for-aws@latest).

구성의 예

액세스 토큰 대신 SigV4를 사용하도록 MCP 클라이언트를 구성하려면를 통해 서버를 실행합니다mcp-proxy-for-aws. 를 에이전트 스페이스의 리전(예: us-east-1){region}으로 바꿉니다.

{
  "mcpServers": {
    "aws-devops-agent": {
      "command": "uvx",
      "timeout": 120000,
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://connect.aidevops.{region}.api.aws/mcp",
        "--service", "aidevops",
        "--region", "{region}"
      ]
    }
  }
}

프록시는 로컬 AWS 자격 증명으로 각 요청에 서명하므로 액세스 토큰이 필요하지 않습니다.

Multi-Agent-Space 라우팅

SigV4 모드에서 각 도구 호출agent_space_id을 전달하여 사용할 에이전트 공간을 지정합니다. 이렇게 하면 단일 클라이언트에서 여러 에이전트 스페이스로 라우팅할 수 있습니다.

A2A 통합

A2A 엔드포인트는 HTTP+JSON 바인딩을 사용하여 A2A v1.0 사양을 구현합니다.

에이전트 카드 검색

다음에서 에이전트 카드를 검색합니다.

GET https://connect.aidevops.{region}.api.aws/.well-known/agent-card.json

지원되는 연산자

• SendMessage - 메시지를 보내고 응답을 받습니다.

• SendStreamingMessage - 생성되는 응답을 스트리밍합니다.

• GetTask - 비동기 작업의 상태를 확인합니다.

• ListTasks - 에이전트 스페이스에 대한 작업을 나열합니다.

• CancelTask - 실행 중인 작업을 취소합니다.

• SubscribeToTask - 서버 전송 이벤트를 통해 작업 업데이트를 구독합니다.

Skills

• 조사 - 운영 문제에 대한 심층 비동기 분석(5~8분).

• 채팅 - 운영 질문에 대한 즉각적인 답변입니다.

보안 고려 사항

토큰 크기 조정

• 최소 권한 사용: 클라이언트가 메시지를 보내거나 작업을 관리해야 하는 operate 경우에만 읽기 전용 통합에 read 대해를 선택합니다.

• 토큰을 주기적으로 교체합니다. 토큰은 구성된 기간(최대 60일) 후에 만료됩니다.

• 환경 변수 또는 보안 암호 관리자에 토큰을 저장합니다. 소스 코드에서 토큰을 하드코딩하지 마십시오.

• 인적 검토 없이 에이전트 응답을 자동 실행하지 마십시오.

IP 허용 목록

액세스 토큰을 생성할 때 선택적으로 IP 허용 목록을 지정할 수 있습니다. 구성된 경우 토큰은 지정된 IP 주소 또는 CIDR 범위에서만 사용할 수 있습니다. 다른 IPs의 요청은 액세스 거부 오류와 함께 거부됩니다.

토큰 교체 및 취소

• 교체 - 토큰의 이름, 범위 및 IP 허용 목록을 유지하면서 토큰을 교체하여 새 토큰 값을 생성합니다. 이전 토큰은 즉시 무효화됩니다. 새 토큰 값으로 클라이언트 구성을 업데이트합니다.

• 취소 - 토큰이 손상된 경우 즉시 취소합니다. 취소된 토큰은 사용할 수 없으며 복원할 수 없습니다.

손상된 토큰에 대한 대응

토큰이 손상되었다고 의심되는 경우 다음 단계를 따르세요.

1. 모든 토큰 액세스 차단 - AWS DevOps 에이전트 콘솔에서 에이전트 스페이스를 열고 구성 탭을 선택한 다음 액세스 토큰 섹션에서 비활성화를 선택합니다. 이렇게 하면 에이전트 스페이스에 대한 모든 토큰 기반 액세스가 즉시 차단됩니다.

2. 손상된 토큰 취소 - 웹 앱에서 설정 > 액세스 토큰으로 이동하여 손상된 토큰을 선택하고 취소를 선택합니다. 액세스 토큰이 비활성화된 상태에서도 토큰을 취소할 수 있습니다.

3. 액세스 토큰 다시 활성화 - 손상된 토큰을 취소한 후 토큰 기반 액세스가 필요한 경우 구성 탭에서 액세스 토큰을 다시 활성화합니다.

프로그래밍 방식으로 토큰 취소

를 사용하여 프로그래밍 방식으로 토큰을 취소할 수도 있습니다awscurl. 다음 명령은 SigV4 인증을 사용합니다. 리전(us-east-1)을 에이전트 스페이스가 생성된 리전으로 바꿉니다.

1단계: 에이전트 스페이스 나열

aws aidevops list-agent-spaces --region us-east-1

2단계: 에이전트 스페이스에 대한 액세스 토큰 나열

awscurl --service aidevops --region us-east-1 \
  -H "Accept: application/json" \
  "https://cp.aidevops.us-east-1.api.aws/v1/agentspaces/{agentSpaceId}/access-tokens"

3단계: 토큰 취소

awscurl --service aidevops --region us-east-1 -X POST \
  -H "Accept: application/json" \
  "https://cp.aidevops.us-east-1.api.aws/v1/agentspaces/{agentSpaceId}/access-tokens/{accessTokenId}/revoke"

{agentSpaceId} 및를 이전 응답의 값으로 {accessTokenId} 바꿉니다.

추적성

액세스 토큰이 사용되는 경우 AWS DevOps Agent는 사용자를 대신하여 작업을 수행하는 역할을 수임합니다. 이 AssumeRole 호출은 토큰과 호출자를 식별하는 세션 태그와 함께 AWS CloudTrail에 로깅됩니다.

• AgentSpaceId - 에이전트 공간의 식별자입니다.

• UserId - 토큰 생성자의 자격 증명입니다.

• AccessTokenId - 토큰의 고유 식별자입니다.

• TokenName - 사용된 액세스 토큰의 이름입니다.

• ClientType - 사용된 프로토콜(MCP, A2A).

• SourceIp - 클라이언트의 IP 주소입니다.

• UserAgent - 클라이언트 사용자-에이전트 문자열(사용 가능한 경우).

직접 MCP 및 A2A 엔드포인트 호출은 두 인증 방법에 대해 CloudTrail에 로깅되지 않습니다. 각 호출에는 CloudTrail에 로깅된 해당 다운스트림 AWS API 호출이 있으며 식별 가능한 역할 세션 이름은 형식입니다token_{spaceId}_{timestamp}_{tokenName}.

VPC 엔드포인트 정책 제한

원격 서버 엔드포인트는 VPC 엔드포인트 정책을 지원하지 않습니다. 액세스 토큰 또는 SigV4 인증을 사용하는 호출은 VPC 엔드포인트 정책에 의해 제한될 수 없습니다.

액세스 토큰 비활성화

액세스 토큰 기능은 기본적으로 꺼져 있습니다. 활성화 후 비활성화하려면:

1. 에이전트 스페이스의 구성 탭을 엽니다.

2. 액세스 토큰 섹션에서 비활성화를 선택합니다.

를 즉시 비활성화하면 모든 토큰 기반 액세스가 차단됩니다. 기존 토큰은 삭제되지 않지만 기능이 다시 활성화될 때까지 사용할 수 없습니다.

조직의 사용자가 액세스 토큰을 활성화하지 못하도록 하려면 액세스 토큰 API 작업 및 UpdateAgentSpace 작업(액세스 토큰 토글을 제어하는)을 거부하는 서비스 제어 정책(SCP)을 생성합니다.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "DenyAccessTokenOperations",
      "Effect": "Deny",
      "Action": [
        "aidevops:UpdateAgentSpace",
        "aidevops:CreateAccessToken",
        "aidevops:GetAccessToken",
        "aidevops:ListAccessTokens",
        "aidevops:RotateAccessToken",
        "aidevops:RevokeAccessToken"
      ],
      "Resource": "*"
    }
  ]
}

문제 해결

증상	원인	해결 방법
HTTP 401 무단	토큰이 유효하지 않거나 만료되었습니다.	웹 앱에서 새 토큰을 생성하거나 기존 토큰을 교체합니다.
HTTP 400 "A2A 버전 헤더 필요"	프로토콜 버전 헤더가 누락되었습니다. A2A v1.0만 지원됩니다.	A2A 요청에 A2A-Version: 1.0 헤더를 추가합니다.
요청 제한 시간	초기 응답에는 5~30초가 걸립니다. 조사에는 5~8분이 소요됩니다.	클라이언트 제한 시간을 최소 120초로 설정합니다.
연결이 거부됨	엔드포인트 URL 또는 리전이 잘못되었습니다.	URL 형식을 확인합니다. https://connect.aidevops.{region}.api.aws