Using external MCP servers

원문 보기 위키 갱신 2026.10.14

출처: 문서

본문

외부 MCP 서버 사용하기

외부 Model Context Protocol(MCP) 서버는 외부 도구와 데이터 소스에 대한 접근을 제공해 에이전틱 검색 기능을 확장해요. MCP 서버에 연결하면 에이전트가 외부 API, 데이터베이스, 서비스를 활용해서 실시간 정보와 전문 기능으로 검색 결과를 한층 강화할 수 있어요.

이 가이드에서는 외부 MCP 서버를 만들고 에이전틱 검색 에이전트에 연결한 다음, 외부 데이터가 필요한 복잡한 쿼리에 외부 도구를 활용해 답변하는 방법을 보여 줘요.

사전 준비 사항

에이전틱 검색에서 외부 MCP 서버를 사용하기 전에 다음 사항을 확인하세요:

MCP 서버를 만들고 배포할 수 있는 권한.
MCP 커넥터 구성에 대한 이해.

1단계: 샘플 products 인덱스 만들기

먼저 외부 MCP 도구 통합을 시연하기 위한 products 인덱스를 만들어요:

PUT /products-index
{
  "settings": {
    "number_of_shards": "4",
    "number_of_replicas": "2"
  },
  "mappings": {
    "properties": {
      "product_name": { "type": "text" },
      "description": { "type": "text" },
      "price": { "type": "float" },
      "currency": { "type": "keyword" },
      "rating": { "type": "float" },
      "review_count": { "type": "integer" },
      "in_stock": { "type": "boolean" },
      "color": { "type": "keyword" },
      "size": { "type": "keyword" },
      "category": { "type": "keyword" },
      "brand": { "type": "keyword" },
      "tags": { "type": "keyword" }
    }
  }
}

{% include copy-curl.html %}

2단계: 샘플 데이터 수집

외부 MCP 도구 사용법을 시연하기 위해 샘플 상품 문서를 추가해요:

POST _bulk
{ "index": { "_index": "products-index", "_id": "1" } }
{ "product_name": "Nike Air Max 270", "description": "Comfortable running shoes with Air Max technology", "price": 150.0, "currency": "USD", "rating": 4.5, "review_count": 1200, "in_stock": true, "color": "white", "size": "10", "category": "shoes", "brand": "Nike", "tags": ["running", "athletic", "comfortable"] }
{ "index": { "_index": "products-index", "_id": "2" } }
{ "product_name": "Adidas Ultraboost 22", "description": "Premium running shoes with Boost midsole", "price": 180.0, "currency": "USD", "rating": 4.7, "review_count": 850, "in_stock": true, "color": "black", "size": "9", "category": "shoes", "brand": "Adidas", "tags": ["running", "premium", "boost"] }
{ "index": { "_index": "products-index", "_id": "3" } }
{ "product_name": "Converse Chuck Taylor", "description": "Classic canvas sneakers", "price": 65.0, "currency": "USD", "rating": 4.2, "review_count": 2100, "in_stock": true, "color": "white", "size": "8", "category": "shoes", "brand": "Converse", "tags": ["casual", "classic", "canvas"] }
{ "index": { "_index": "products-index", "_id": "4" } }
{ "product_name": "Puma RS-X", "description": "Retro-inspired running shoes with modern comfort", "price": 120.0, "currency": "USD", "rating": 4.3, "review_count": 750, "in_stock": true, "color": "black", "size": "9", "category": "shoes", "brand": "Puma", "tags": ["retro", "running", "comfortable"] }

{% include copy-curl.html %}

3단계: 외부 MCP 서버 만들기

샘플 MCP 서버를 만들어요. 이 MCP 서버는 사용자 선호에 따라 브랜드를 서로 다른 티어(favorites, budget, luxury)로 분류하는 brand_collection_tool을 제공해요. 에이전트는 자연어 쿼리를 처리할 때 이 도구를 사용해 어떤 브랜드가 특정 카테고리에 속하는지 파악할 수 있어요:

from fastmcp import FastMCP

mcp = FastMCP("brands_server")

@mcp.tool
def brand_collection_tool(category: str) -> list[str]:
    """This is the collection of brands for a given category. There are 3 categories: 1. favorites, 2. budget, 3. luxury. If the category is not one of these, return all the brands."""
    favorites = ["Nike", "Adidas", "Reebok"]
    budget = ["Puma", "New Balance", "Under Armour"]
    luxury = ["Phoenix Motors", "Crystal Palace", "Royal Oak"]
    if category == "favorites":
        return favorites
    elif category == "budget":
        return budget
    elif category == "luxury":
        return luxury
    else:
        return favorites + budget + luxury

if __name__ == "__main__":
    # Streamable HTTP transport; no session/state persisted between requests
    mcp.run(transport="streamable-http")

{% include copy.html %}

4단계: MCP 커넥터 만들기

에이전틱 검색 에이전트를 외부 MCP 서버에 연결하려면 MCP 커넥터를 등록해요. MCP 커넥터는 mcp_streamable_http 프로토콜을 사용해 외부 MCP 서버와 통신해요. <Your MCP Server URL>은 MCP 서버가 실행 중인 실제 URL로, <Your API Key>는 적절한 인증 키로 바꿔 주세요:

POST /_plugins/_ml/connectors/_create
{
  "name": "Brands MCP Connector",
  "description": "The connector to external brands MCP server",
  "version": 1,
  "protocol": "mcp_streamable_http",
  "parameters": {
    "endpoint": "/mcp"
  },
  "credential": {
    "access_key": "<Your API Key>"
  },
  "url": "<Your MCP Server URL>",
  "headers": {
    "Authorization": "Bearer ${credential.access_key}",
    "Content-Type": "application/json"
  }
}

{% include copy-curl.html %}

5단계: 에이전트용 모델 만들기

대화형 에이전트와 QueryPlanningTool이 모두 사용할 모델을 등록해요:

POST /_plugins/_ml/models/_register
{
  "name": "My OpenAI model: gpt-5",
  "function_name": "remote",
  "description": "Model for agentic search with external MCP tools",
  "connector": {
    "name": "My openai connector: gpt-5",
    "description": "The connector to openai chat model",
    "version": 1,
    "protocol": "http",
    "parameters": {
      "model": "gpt-5"
    },
    "credential": {
      "openAI_key": "<OPEN AI KEY>"
    },
    "actions": [
      {
        "action_type": "predict",
        "method": "POST",
        "url": "https://api.openai.com/v1/chat/completions",
        "headers": {
          "Authorization": "Bearer ${credential.openAI_key}"
        },
        "request_body": """{ "model": "${parameters.model}", "messages": [{"role":"developer","content":"${parameters.system_prompt}"},${parameters._chat_history:-}{"role":"user","content":"${parameters.user_prompt}"}${parameters._interactions:-}], "reasoning_effort":"low"${parameters.tool_configs:-}}"""
      }
    ]
  }
}

{% include copy-curl.html %}

6단계: MCP 커넥터를 포함한 에이전트 만들기

외부 도구에 접근할 수 있도록 MCP 커넥터를 포함하는 대화형 에이전트를 등록해요:

POST /_plugins/_ml/agents/_register
{
  "name": "E-commerce Agent with External Tools",
  "type": "conversational",
  "description": "Agentic search agent with external MCP tools for brand categorization",
  "llm": {
    "model_id": "<Model ID from Step 5>",
    "parameters": {
      "max_iteration": 15
    }
  },
  "memory": {
    "type": "conversation_index"
  },
  "parameters": {
    "_llm_interface": "openai/v1/chat/completions",
    "mcp_connectors": [
      {
        "mcp_connector_id": "<MCP Connector ID from Step 4>"
      }
    ]
  },
  "tools": [
    {
      "type": "ListIndexTool",
      "name": "ListIndexTool"
    },
    {
      "type": "IndexMappingTool",
      "name": "IndexMappingTool"
    },
    {
      "type": "QueryPlanningTool"
    }
  ],
  "app_type": "os_chat"
}

{% include copy-curl.html %}

에이전트 구성에는 다음이 포함돼요:

MCP 커넥터: 추가 도구를 제공하는 외부 MCP 서버에 대한 연결.
표준 도구: 핵심 에이전틱 검색 기능을 위한 ListIndexTool, IndexMappingTool, QueryPlanningTool.
외부 도구: MCP 커넥터를 통해 자동으로 사용 가능(예: brand_collection_tool).

7단계: 에이전틱 검색 파이프라인 만들기

외부 MCP 도구를 갖춘 에이전트를 사용하는 검색 파이프라인을 만들어요:

PUT _search/pipeline/mcp-agentic-pipeline
{
  "request_processors": [
    {
      "agentic_query_translator": {
        "agent_id": "<Agent ID from Step 6>"
      }
    }
  ],
  "response_processors": [
    {
      "agentic_context": {
        "agent_steps_summary": true,
        "dsl_query": true
      }
    }
  ]
}

{% include copy-curl.html %}

8단계: 외부 도구로 에이전틱 검색 실행하기

외부 MCP 도구 사용이 필요한 자연어 쿼리를 보내요:

POST products-index/_search?search_pipeline=mcp-agentic-pipeline
{
  "query": {
    "agentic": {
      "query_text": "Find red shoes under 200 USD from my favorite brands"
    }
  }
}

{% include copy-curl.html %}

에이전트는 다음과 같이 이 쿼리를 처리해요:

외부 MCP 도구 사용: favorites 카테고리로 brand_collection_tool을 호출해 선호 브랜드 목록을 가져와요.
인덱스 탐색: ListIndexTool을 사용해 관련 인덱스를 찾아요.
스키마 분석: IndexMappingTool을 사용해 인덱스 구조를 파악해요.
쿼리 계획 수립: QueryPlanningTool을 사용해 최종 query domain-specific language(DSL) 쿼리를 생성해요.

응답에는 매칭되는 상품과 상세한 에이전트 실행 정보가 담겨 있어요. agent_steps_summary는 에이전트가 사용자 요청을 이해하고 적절한 검색 쿼리를 생성하기 위해 외부 MCP 도구(brand_collection_tool)를 포함한 여러 도구를 어떻게 오케스트레이션했는지 보여 줘요:

{
  "took": 29942,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 2,
      "relation": "eq"
    },
    "max_score": 0.0,
    "hits": [
      {
        "_index": "products-index",
        "_id": "1",
        "_score": 0.0,
        "_source": {
          "product_name": "Nike Air Max 270",
          "description": "Comfortable running shoes with Air Max technology",
          "price": 150.0,
          "currency": "USD",
          "rating": 4.5,
          "review_count": 1200,
          "in_stock": true,
          "color": "white",
          "size": "10",
          "category": "shoes",
          "brand": "Nike",
          "tags": [
            "running",
            "athletic",
            "comfortable"
          ]
        }
      },
      {
        "_index": "products-index",
        "_id": "2",
        "_score": 0.0,
        "_source": {
          "product_name": "Adidas Ultraboost 22",
          "description": "Premium running shoes with Boost midsole",
          "price": 180.0,
          "currency": "USD",
          "rating": 4.7,
          "review_count": 850,
          "in_stock": true,
          "color": "black",
          "size": "9",
          "category": "shoes",
          "brand": "Adidas",
          "tags": [
            "running",
            "premium",
            "boost"
          ]
        }
      }
    ]
  },
  "ext": {
    "agent_steps_summary": "I have these tools available: [ListIndexTool, IndexMappingTool, query_planner_tool, brand_collection_tool]\nFirst I used: brand_collection_tool — input: \"favorites\"; context gained: \"User favourite brands are [\"Nike\",\"Adidas\",\"Reebok\"]\"\nSecond I used: ListIndexTool — input: \"[]\"; context gained: \"Found indices; products-index appears relevant\"\nThird I used: IndexMappingTool — input: \"products-index\"; context gained: \"Index contains product-related fields\"\nFourth I used: query_planner_tool — qpt.question: \"Find shoes priced under 200 USD from brands Nike, Adidas, and Reebok.\"; index_name_provided: \"products-index\"\nValidation: qpt output is valid and matches the user's request.",
    "memory_id": "XRzFl5kB-5P992SCeeqO",
    "dsl_query": "{\"size\":10.0,\"query\":{\"bool\":{\"filter\":[{\"term\":{\"category\":\"shoes\"}},{\"term\":{\"currency\":\"USD\"}},{\"range\":{\"price\":{\"lte\":200.0}}},{\"terms\":{\"brand\":[\"Nike\",\"Adidas\",\"Reebok\"]}}]}}}"
  }
}

다음 단계

MCP 커넥터 구성 -- 외부 도구 통합을 위한 MCP 커넥터 구성 방법을 자세히 알아보세요.
에이전틱 검색 에이전트 구성 -- 다양한 모델과 도구로 에이전트 동작을 구성해 보세요.
대화형 에이전트 사용하기 -- 대화형 에이전트와 고급 기능을 자세히 알아보세요.

더 알아보기 (Learn more)

원문 전체: https://docs.opensearch.org/latest/vector-search/ai-search/agentic-search/mcp-server/

Using external MCP servers

본문

외부 MCP 서버 사용하기

사전 준비 사항

1단계: 샘플 products 인덱스 만들기

2단계: 샘플 데이터 수집

3단계: 외부 MCP 서버 만들기

4단계: MCP 커넥터 만들기

5단계: 에이전트용 모델 만들기

6단계: MCP 커넥터를 포함한 에이전트 만들기

7단계: 에이전틱 검색 파이프라인 만들기

8단계: 외부 도구로 에이전틱 검색 실행하기

다음 단계

더 알아보기 (Learn more)

함께 읽는 실무 이야기