Using the OpenSearch MCP Server
출처: 문서
본문
OpenSearch MCP 서버 사용하기
이 가이드에서는 OpenSearch MCP Server를 설치하고, AI 클라이언트나 에이전트 프레임워크에 연결하고, OpenSearch 클러스터에 첫 번째 도구 호출을 수행하는 방법을 알아요.
사전 요구 사항
OpenSearch MCP 서버를 사용하기 전에 다음 구성 요소가 있는지 확인하세요:
- 서버를 실행하는 머신에서 접근할 수 있는, 실행 중인 OpenSearch 클러스터.
- 해당 클러스터의 자격 증명(자체 관리형 클러스터의 경우 기본 인증 또는 상호 TLS(mTLS) 인증서).
- Python 3.11 이상.
- 다음 도구 중 하나:
uv(권장) -- 로컬 설치 없이uvx로 서버를 실행해요.pip-- 패키지를 Python 환경에 설치해요.
1단계: 서버 구성하기
다음 설치 옵션 중 하나를 선택하세요:
옵션 1: uvx로 실행하기(권장)
패키지를 설치하지 않고 서버를 실행할 수 있는 uvx 명령어를 제공하는 uv를 설치하세요:
pip install uv
{% include copy.html %}
uvx를 사용하면 Python 환경에 설치하지 않고도 서버를 바로 실행할 수 있어요. 이 가이드의 모든 구성 예제는 uvx를 사용해요.
옵션 2: pip로 설치하기
opensearch-mcp-server-py 패키지를 Python 환경에 직접 설치하세요:
pip install opensearch-mcp-server-py
{% include copy.html %}
이 옵션을 사용하는 경우, 뒤에 나오는 구성 예제에서 "command": "uvx"를 "command": "python"으로, "args": ["opensearch-mcp-server-py"]를 "args": ["-m", "mcp_server_opensearch"]로 바꾸세요.
2단계: 코딩 어시스턴트에 서버 연결하기
Claude Desktop, Cursor, Kiro 같은 코딩 어시스턴트는 mcp.json 구성 파일을 읽어서 MCP 서버를 찾아요. 어시스턴트가 시작될 때 서버는 자식 프로세스로 자동 실행돼요.
Claude Desktop
Claude Desktop에 연결하려면 Settings > Developer > Edit Config를 여세요. 구성 파일은 보통 macOS에서 ~/Library/Application Support/Claude/claude_desktop_config.json에 위치해요. 다음 항목을 추가하세요:
{
"mcpServers": {
"opensearch": {
"command": "uvx",
"args": ["opensearch-mcp-server-py"],
"env": {
"OPENSEARCH_URL": "http://localhost:9200",
"OPENSEARCH_USERNAME": "admin",
"OPENSEARCH_PASSWORD": "admin",
"OPENSEARCH_SSL_VERIFY": "false"
}
}
}
}
{% include copy.html %} 구성 파일을 저장하고 Claude Desktop을 재시작하세요. 재시작하면 Tools 패널에 OpenSearch 도구가 나타나요.
Cursor
Cursor에 연결하려면 Cursor Settings > MCP를 열고 새 서버를 추가하세요. 또는 ~/.cursor/mcp.json 구성 파일을 직접 편집해도 돼요:
{
"mcpServers": {
"opensearch": {
"command": "uvx",
"args": ["opensearch-mcp-server-py"],
"env": {
"OPENSEARCH_URL": "http://localhost:9200",
"OPENSEARCH_USERNAME": "admin",
"OPENSEARCH_PASSWORD": "admin",
"OPENSEARCH_SSL_VERIFY": "false"
}
}
}
}
{% include copy.html %}
Kiro
Kiro에 연결하려면 워크스페이스의 .kiro/settings/mcp.json 또는 전역 구성용 ~/.kiro/settings/mcp.json 구성 파일을 편집하고 다음 항목을 추가하세요:
{
"mcpServers": {
"opensearch": {
"command": "uvx",
"args": ["opensearch-mcp-server-py"],
"env": {
"OPENSEARCH_URL": "http://localhost:9200",
"OPENSEARCH_USERNAME": "admin",
"OPENSEARCH_PASSWORD": "admin",
"OPENSEARCH_SSL_VERIFY": "false"
}
}
}
}
{% include copy.html %}
보안 없는 클러스터
보안 없이 시작한 로컬 개발 클러스터(예: docker run -p 9200:9200 opensearchproject/opensearch:latest -e "discovery.type=single-node" -e "DISABLE_SECURITY_PLUGIN=true")에는 자격 증명 대신 OPENSEARCH_NO_AUTH를 사용하세요:
{
"mcpServers": {
"opensearch": {
"command": "uvx",
"args": ["opensearch-mcp-server-py"],
"env": {
"OPENSEARCH_URL": "http://localhost:9200",
"OPENSEARCH_NO_AUTH": "true"
}
}
}
}
{% include copy.html %}
앞선 예제는 로컬 개발용 기본 자격 증명을 사용해요. 프로덕션에서는 기본 자격 증명을 절대 사용하지 마세요. {: .warning}
3단계: 연결 테스트하기
클라이언트가 연결되면 자연어 질문을 해보세요. 예를 들면:
내 클러스터에는 어떤 인덱스가 있고, 어느 인덱스에 문서가 가장 많나요?
AI가 ListIndexTool을 선택하고, 서버가 _cat/indices를 호출한 뒤 결과가 모델로 반환돼요. "지난 1시간 동안 logs 인덱스에서 에러를 검색해 줘" 같은 후속 질문에는 모델이 SearchIndexTool을 선택하고 query DSL 쿼리를 자동으로 만들어요.
에이전트 프레임워크 통합
파이프라인, 챗봇, 자동화 워크플로를 만들려면 MCP 서버를 에이전트 프레임워크에 연결하면 돼요. 다음 예제는 stdio 트랜스포트를 사용하는데, 이를 통해 프레임워크가 MCP 서버를 서브프로세스로 자동 실행할 수 있어요.
Strands Agents
Strands Agents는 AI 에이전트를 만들기 위한 오픈 소스 Python SDK예요. MCPClient 클래스를 사용해서 MCP 서버에 연결해요. stdio 트랜스포트를 사용하면 프레임워크가 MCP 서버를 서브프로세스로 실행해요.
Strands Agents에 연결하려면 다음 단계를 따르세요:
- 필요한 패키지를 설치하세요:
{% include copy.html %}pip install strands-agents strands-agents-tools MCPClient클래스를 사용해서 OpenSearch MCP 서버에 연결하세요:
{% include copy.html %}from mcp import StdioServerParameters from strands import Agent from strands.tools.mcp import MCPClient # The framework launches the MCP server as a subprocess using stdio. # No separate server process needed. mcp_client = MCPClient(lambda: StdioServerParameters( command="uvx", args=["opensearch-mcp-server-py"], env={ "OPENSEARCH_URL": "http://localhost:9200", "OPENSEARCH_USERNAME": "admin", "OPENSEARCH_PASSWORD": "admin", "OPENSEARCH_SSL_VERIFY": "false", } )) with mcp_client: # Discover all tools exposed by the MCP server tools = mcp_client.list_tools_sync() # Create an agent with those tools. # By default, Strands uses Amazon Bedrock. To use a different model, # pass a model= argument. See https://strandsagents.com/docs for options. agent = Agent(tools=tools) # Natural-language queries — the agent picks the right tool automatically print(agent("List all indexes in the cluster and show their document counts.")) print(agent("Search the 'products' index for items where category is 'electronics'.")) print(agent("What is the health status of the cluster?"))
LangGraph
LangGraph는 상태를 가지는 다단계 에이전트 워크플로를 만들기 위한 프레임워크예요. langchain-mcp-adapters를 사용해서 MCP 도구를 LangGraph에 연결하세요. stdio 트랜스포트를 사용하면 프레임워크가 서버 프로세스를 대신 관리해 줘요.
LangGraph에 연결하려면 다음 단계를 따르세요:
- 필요한 패키지를 설치하세요:
{% include copy.html %}pip install langgraph langchain-mcp-adapters langchain-openai langchain-mcp-adapters를 사용해서 MCP 도구를 LangGraph에 연결하세요:
{% include copy.html %}import asyncio from langchain_mcp_adapters.client import MultiServerMCPClient from langchain_openai import ChatOpenAI from langgraph.prebuilt import create_react_agent async def main(): async with MultiServerMCPClient({ "opensearch": { "transport": "stdio", "command": "uvx", "args": ["opensearch-mcp-server-py"], "env": { "OPENSEARCH_URL": "http://localhost:9200", "OPENSEARCH_USERNAME": "admin", "OPENSEARCH_PASSWORD": "admin", "OPENSEARCH_SSL_VERIFY": "false", }, } }) as mcp_client: tools = mcp_client.get_tools() # Create a ReAct agent with the OpenSearch tools. # Replace ChatOpenAI with any LangChain-compatible LLM. llm = ChatOpenAI(model="gpt-4o") agent = create_react_agent(llm, tools) # Single query result = await agent.ainvoke({ "messages": [{"role": "user", "content": "List all indexes and tell me which one is largest."}] }) print(result["messages"][-1].content) # Multi-step reasoning result = await agent.ainvoke({ "messages": [{"role": "user", "content": ( "Find all indexes that contain 'log' in their name, " "then search the largest one for ERROR level entries from the last 24 hours." )}] }) print(result["messages"][-1].content) asyncio.run(main())
LangChain(LangGraph 없이)
그래프 추상화 없이 단일 에이전트 구성으로 LangChain에 연결하려면 LangGraph 섹션과 동일한 패키지를 사용해서 tool-calling 에이전트를 만드세요:
import asyncio
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain_openai import ChatOpenAI
from langchain.agents import create_tool_calling_agent, AgentExecutor
from langchain_core.prompts import ChatPromptTemplate
async def main():
async with MultiServerMCPClient({
"opensearch": {
"transport": "stdio",
"command": "uvx",
"args": ["opensearch-mcp-server-py"],
"env": {
"OPENSEARCH_URL": "http://localhost:9200",
"OPENSEARCH_USERNAME": "admin",
"OPENSEARCH_PASSWORD": "admin",
"OPENSEARCH_SSL_VERIFY": "false",
},
}
}) as mcp_client:
tools = mcp_client.get_tools()
llm = ChatOpenAI(model="gpt-4o")
prompt = ChatPromptTemplate.from_messages([
("system", "You are a helpful assistant with access to OpenSearch tools."),
("human", "{input}"),
("placeholder", "{agent_scratchpad}"),
])
agent = create_tool_calling_agent(llm, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
await agent_executor.ainvoke({"input": "How many documents are in the 'orders' index?"})
asyncio.run(main())
{% include copy.html %}
멀티 클러스터 구성
MCP 서버를 여러 클러스터에 연결하려면 원하는 위치에 config.yml 파일을 만드세요:
version: "1.0"
description: "OpenSearch cluster configurations"
clusters:
local-dev:
opensearch_url: "http://localhost:9200"
opensearch_username: "admin"
opensearch_password: "admin"
staging:
opensearch_url: "https://staging.example.com:9200"
opensearch_username: "admin"
opensearch_password: "staging_password"
opensearch_ca_cert_path: "/path/to/ca.crt"
{% include copy.html %}
구성 파일의 전체 경로를 지정해서 서버를 multi 모드로 시작하세요:
python -m mcp_server_opensearch --mode multi --config /path/to/config.yml --transport stream
{% include copy.html %}
멀티 클러스터 모드에서는 모든 도구 호출에 구성 파일의 키와 일치하는 opensearch_cluster_name 파라미터가 반드시 포함되어야 해요. 코딩 어시스턴트를 사용할 때는 시스템 프롬프트에 사용 가능한 클러스터 이름을 포함하세요.
인증 옵션
서버는 다음 순서로 인증 방식을 시도해요:
- 인증 없음 -- 열려 있는 클러스터에는
OPENSEARCH_NO_AUTH=true. - 헤더 기반 인증 --
OPENSEARCH_HEADER_AUTH=true. 서버가 호출마다 요청 헤더에서 자격 증명을 읽기 때문에, 스트리밍 트랜스포트를 사용할 때 세션마다 다른 자격 증명을 쓸 수 있어요. - 기본 인증 --
OPENSEARCH_USERNAME과OPENSEARCH_PASSWORD. - 상호 TLS --
OPENSEARCH_CA_CERT_PATH,OPENSEARCH_CLIENT_CERT_PATH,OPENSEARCH_CLIENT_KEY_PATH. 기본 인증과 함께 또는 없이 사용할 수 있어요.
IAM 및 AWS 자격 증명 옵션에 대한 정보는 opensearch-mcp-server-py 저장소를 참고하세요.
트랜스포트: Stdio와 스트리밍
서버는 다음 트랜스포트 옵션을 지원해요.
| 트랜스포트 | 언제 사용하나요 | 시작 방법 |
|---|---|---|
stdio(기본값) |
코딩 어시스턴트(Claude Desktop, Cursor, Kiro). 클라이언트가 서버를 자식 프로세스로 실행해요. | mcp.json에서 구성해요. 클라이언트가 시작되면 서버도 자동으로 시작돼요. |
stream(streamable-http) |
에이전트 프레임워크(Strands, LangGraph, LangChain)와 원격/공유 배포. | python -m mcp_server_opensearch --transport stream |
스트리밍 트랜스포트는 기본적으로 0.0.0.0:9900에 바인딩돼요. 다른 호스트나 포트를 사용하려면 --host와 --port를 지정하세요.
자주 발생하는 문제
다음 목록은 자주 발생하는 연결 및 구성 문제를 설명해요:
- 클라이언트에 도구가 나타나지 않음: 클라이언트의 MCP 로그를 확인해서 서버가 성공적으로 실행됐는지 확인하세요.
curl http://localhost:9200을 실행해서 OpenSearch 클러스터에 접근 가능한지 확인하세요. - 프레임워크가 스트리밍 서버에 연결할 수 없음:
curl http://localhost:9900/mcp를 실행해서 서버가 떠 있는지 확인하세요. 프레임워크 구성의 URL이/mcp경로까지 포함해서 서버 URL과 정확히 일치하는지 확인하세요. - 멀티 클러스터 모드에서 AI 모델이 잘못된 클러스터를 선택함: 시스템 프롬프트에 사용 가능한 클러스터 이름과 각각의 용도 목록을 제공하세요.
다음 단계
- Kubernetes 배포, 구조화된 로깅, 도구 필터링, 도구 커스터마이징에 대한 정보는
opensearch-mcp-server-py저장소를 참고하세요. - MCP 도구를 OpenSearch 에이전트에 통합하려면(외부 에이전트에 OpenSearch를 노출하는 대신) MCP 도구 사용하기를 참고하세요.
- AI 어시스턴트가 OpenSearch 작업을 수행하도록 안내하는 구조화된 워크플로는 에이전트 스킬을 참고하세요.