기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# AWS MCP 서버 설정
AWS MCP 서버는 Agent Toolkit for의 관리형 모델 컨텍스트 프로토콜 서버입니다 AWS. 이를 통해 AI 에이전트는 사용자를 대신하여 AWS API 호출을 AWS 실행하고, 샌드박스 환경에서 스크립트를 실행하고, 온디맨드 방식으로 AWS 기술( 포함[amazon-opensearch-service 스킬](amazon-opensearch-service-skill.md))을 제공할 수 있는 인증된 액세스 권한을 얻을 수 있습니다. 이를 사용하여 에이전트의 OpenSearch Service 도메인 및 OpenSearch Serverless 컬렉션을 사용할 수 있습니다.
**참고**
AWS MCP 서버는 퍼블릭 Amazon OpenSearch Service 엔드포인트에 연결됩니다. VPC에 배포된 도메인 또는 컬렉션은 지원하지 않습니다. OpenSearch Service 도메인 또는 OpenSearch Serverless 컬렉션에서 VPC 액세스를 사용하는 경우 로컬 구성을 통한 VPC 연결을 지원하는 오픈 소스 [opensearch-mcp-server-py](https://github.com/opensearch-project/opensearch-mcp-server-py)를 대신 사용합니다.
## 사전 조건
+ 에이전트 툴킷을 지원하는 AI 코딩 에이전트 AWS (예: Kiro, Claude Code, Cursor, Codex).
+ AWS 실행하려는 OpenSearch 작업에 대한 권한이 있는 로컬로 구성된 자격 증명(예: AWS CLI 프로필 또는 환경 자격 증명). 도메인은 섹션을 참조하고, 서버리스[ID 기반 정책](ac.md#ac-types-identity)는 섹션을 참조하세요[Amazon OpenSearch Serverless를 위한 데이터 액세스 제어](serverless-data-access.md).
## aws-data-analytics 플러그인 설치(권장)
`aws-data-analytics` 플러그인은 AWS MCP 서버 구성과 `amazon-opensearch-service` 스킬을 단일 설치로 번들링하므로 MCP 엔드포인트를 구성하거나 스킬을 별도로 설치할 필요가 없습니다.
**Claude 코드**
```
/plugin install aws-data-analytics@claude-plugins-official
/reload-plugins
```
**코덱**
```
codex plugin marketplace add aws/agent-toolkit-for-aws
```
그런 다음 Codex를 시작하고를 실행`/plugins`하여 `aws-data-analytics` 플러그인을 찾아 설치합니다.
## AWS MCP 서버 직접 구성
에이전트가 플러그인을 지원하지 않는 경우 AWS MCP 서버를 직접 구성합니다. Agent Toolkit for AWS 설명서의 [AWS MCP 서버 설정에](https://docs.aws.amazon.com/agent-toolkit/latest/userguide/getting-started-aws-mcp-server.html) 따라 에이전트에게 OpenSearch 질문을 합니다. 그러면 서버를 통해 런타임 시 `amazon-opensearch-service` 스킬을 발견합니다.
## 기술 없이 AWS MCP 서버 사용
`amazon-opensearch-service` 스킬을 로드하지 않고도 AWS MCP 서버를 직접 사용할 수 있습니다. 이 모드에서 에이전트는 서버의 기본 제공 `call_aws` 도구를 사용하여 AWS API 작업을 직접 호출합니다. 이는 임시 작업이나 에이전트가 수행하는 API 호출을 정확하게 제어하려는 경우에 유용합니다.
예를 들어 OpenSearch Serverless 컬렉션을 생성하려면
```
Create an OpenSearch Serverless search collection named "my-collection" in us-east-1
```
에이전트는 구성된 자격 증명을 사용하여 사용자를 대신하여 OpenSearch Serverless `CreateCollection` API를 호출합니다.
```
{
"name": "my-collection",
"type": "SEARCH",
"description": "My search collection"
}
```
기술 없이 기존 리소스에 대해 작업을 실행할 수도 있습니다. 예제:
```
List all my OpenSearch Service domains in us-east-1
Show the cluster health for my domain named production-domain
Create an index called products in my collection endpoint
```
AWS MCP 서버는 인증을 처리하고 자연어 요청을 적절한 AWS API 또는 OpenSearch API 호출로 변환합니다.
## 설정 확인
설치 후 새 구성을 로드하도록 에이전트를 다시 시작합니다. 그런 다음 다음과 같이 질문합니다.
```
What AWS skills do you have available for OpenSearch?
```
에이전트는 `amazon-opensearch-service` 스킬을 보고해야 합니다. *"OpenSearch Service 도메인 나열"*과 같은 작업을 시도합니다. 에이전트는 구성된 자격 증명을 사용하여 AWS MCP 서버를 통해 호출을 실행합니다.
## 보안 고려 사항
AWS MCP 서버는 사용자가 제공한 자격 증명으로 실행됩니다. 다음 관행을 따릅니다.
+ **최소 권한 자격 증명을 사용합니다.** 전용 IAM 보안 주체의 범위를 에이전트에게 필요한 OpenSearch 리소스 및 작업으로 지정합니다. 관리자 자격 증명을 사용하지 마세요.
+ **개발과 프로덕션을 구분합니다.** 탐색할 비프로덕션 리소스를 서버를 가리키고 프로덕션 변경 전에 확인이 필요합니다.
+ **자격 증명을 보호합니다.** 정적 액세스 키보다 IAM 역할 및 AWS CLI 프로파일을 선호하며 소스 제어의 구성 파일에 암호를 커밋하지 않습니다.
+ **도구 출력을 검토합니다.** MCP 도구 응답은 컨텍스트로 모델에 반환됩니다. 모델 공급자에게 노출하지 않으려는 민감한 데이터가 있는 인덱스에 대해 서버를 실행하지 마십시오.
## 문제 해결
+ **에이전트에 OpenSearch 기술 또는 도구가 표시되지 않음 **- 플러그인 또는 MCP 구성이 유효한지 확인하고 에이전트를 완전히 다시 시작합니다. 대부분의 에이전트는 시작 시에만 MCP 서버를 로드합니다.
+ **호출은 403 금지됨 반환** - 자격 증명에 호출 중인 API에 대한 권한이 없습니다. 도메인의 경우 보안 주체의 도메인 액세스 정책 및 IAM 정책을 검토합니다. 서버리스의 경우 컬렉션의 데이터 액세스 정책을 검토합니다.
## 에이전트 프레임워크와 함께 사용
프로그래밍 방식의 워크플로를 위해 AWS MCP 서버를 Python 에이전트 프레임워크에 통합할 수 있습니다. 다음 예제는 OpenSearch 및 기타 AWS 서비스에 대한 인증된 액세스를 제공하는 AWS MCP Server 엔드포인트에 연결합니다.
### Strands Agents
[Strands Agents](https://strandsagents.com)는 기본 MCP 지원 및 Amazon Bedrock을 기본 모델 공급자로 사용하는 AWS네이티브 에이전트 SDK입니다.
```
from strands import Agent
from strands.tools.mcp import MCPClient
from mcp_proxy_for_aws.client import aws_iam_streamablehttp_client
ENDPOINT = "https://aws-mcp.us-east-1.api.aws/mcp"
AWS_REGION = "us-east-1"
opensearch_client = MCPClient(
lambda: aws_iam_streamablehttp_client(
endpoint=ENDPOINT,
aws_service="aws-mcp",
aws_region=AWS_REGION,
)
)
with opensearch_client:
agent = Agent(tools=opensearch_client.list_tools_sync())
response = agent("What OpenSearch Service domains do I have?")
print(response)
```
필수 패키지를 설치합니다.
```
pip install strands-agents mcp-proxy-for-aws
```
### LangGraph
[LangGraph](https://github.com/langchain-ai/langgraph)는 상태 저장 에이전트를 빌드하기 위한 하위 수준 오케스트레이션 프레임워크입니다. 다음 예제에서는 `mcp-proxy-for-aws`를 사용하여 인증된 전송`langchain-mcp-adapters`을 제공하고 Amazon Bedrock이 지원하는 LangChain 에이전트에 AWS MCP 도구를 로드합니다.
```
import asyncio
from mcp import ClientSession
from mcp_proxy_for_aws.client import aws_iam_streamablehttp_client
from langchain_mcp_adapters.tools import load_mcp_tools
from langchain_aws import ChatBedrock
from langchain.agents import create_agent
ENDPOINT = "https://aws-mcp.us-east-1.api.aws/mcp"
AWS_REGION = "us-east-1"
async def main():
async with aws_iam_streamablehttp_client(
endpoint=ENDPOINT,
aws_service="aws-mcp",
aws_region=AWS_REGION,
) as (read_stream, write_stream, _get_session_id):
async with ClientSession(read_stream, write_stream) as session:
await session.initialize()
tools = await load_mcp_tools(session)
model = ChatBedrock(
model_id="us.anthropic.claude-opus-4-8",
region_name=AWS_REGION,
)
agent = create_agent(model, tools)
result = await agent.ainvoke(
{"messages": [{"role": "user", "content": "What OpenSearch Service domains do I have?"}]}
)
print(result["messages"][-1].content)
asyncio.run(main())
```
필수 패키지를 설치합니다.
```
pip install mcp-proxy-for-aws langchain langchain-aws langchain-mcp-adapters langgraph
```
## 추가 정보
+ [AWS 구성 요소용 에이전트 도구 키트](https://docs.aws.amazon.com/agent-toolkit/latest/userguide/components.html)