UV·Python·mcp-use로 구현하는 MCP Agent

Model Context Protocol (MCP)은 AI 에이전트가 외부 도구·데이터와 표준 방식으로 상호작용하도록 설계된 개방형 프로토콜입니다. MCP는 server, client, host 세 가지 구성요소로 나뉩니다.

---

MCP host

MCP host는 사용자와 Agent사이의 인터페이스 (Claude Desktop 혹은 IDE) 역활을 하며 MCP client와 server들을 이용하여 외부 툴 혹은 데이터에 접속하는 역할을 수행합니다. 과거에는 Anthropic Claude Desktop을 host로 쓰는 방식이 소개되었으나, 별도 데스크톱 앱·라이선스·API 키 관리가 필요하고 Claude 생태계에 종속되는 문제가 있었습니다. mcp-use는 오픈소스 Python/Node 패키지로, LangChain LLM(예: GPT-4, Claude, Groq)과 MCP server를 단 6줄로 연결할 수 있어 종속성을 없애고 멀티서버·멀티모델을 지원합니다. 

MCP Client

MCP client는 host 내에서 MCP 프로토콜을 관리하고 host의 서비스에 필요한 기능을 가진 MCP 서버들과의 연결을 담당하는 역할을 합니다. MCP client는 host에서 사용할 기능별 서버들에 대한 접속을 각 서버 이름과 접속 방법이 기록된 Json 파일을 통해서 해당 서버와의 연결을 담당하고 MCP host에서 요구하는 도구나 데이터를 제공합니다.

MCP server

MCP server는 MCP host에서 필요로 하는 자원들 (데이터베이스, 웹 데이터, 로컬 파일)에 대한 실질적인 연결과 관리를 지원하는 모듈입니다. MCP 서버는 도구 목록을 노출하고 세션별 컨텍스트를 관리합니다. 본 예제에서는 Astral UV를 이용해 Python 실행·패키지 관리 환경을 구축합니다. UV는 Rust로 작성되어 설치/의존성 해결 속도가 뛰어나며, uv run으로 스크립트를 즉시 실행할 수 있어 컨테이너·CI 환경에 최적화돼 있습니다.

전체 아키텍처

MCP를 이용한 Agent 시스템 아키텍처

---

개발환경 설정

시스템 아키텍처에 표시된 것 처럼 본 문서에서는 UV를 이용하여 MCP 서버를 서빙하고 Claude Desktop 대신 오픈소스 솔루션인 mcp-use를 사용하여 MCP host와 client를 구성하기 위한 환경 설정을 설명합니다.

# uv install
curl -LsSf https://astral.sh/uv/install.sh | sh

# initialize uv project 
uv init "Your MCP Server Project Directory" 

# install required python packages for the uv project
uv add "mcp[cli]" mcp-use langchain-openai langchain-community python-dotenv

server.py – Wiki 혹은 Arxiv에서 문서를 검색하는 간단한 MCP 서버

이 코드에서는 langchain에서 제공하는 Wikipedia 및 Arxiv API wrapper를 이용하여 사용자가 요청한 아이템에 해당하는 내용을 Wikipedia 혹은 Arxiv에서 검색하여 알려주는 기능을 가진 "doc-server"라는 MCP용 서버를 어떻게 구현하는지 보여줍니다.

# file name is 'server.py'

from mcp.server.fastmcp import FastMCP
from langchain_community.utilities import WikipediaAPIWrapper, ArxivAPIWrapper
from langchain_community.tools import WikipediaQueryRun, ArxivQueryRun

mcp = FastMCP("doc-server")

wiki_wrapper = WikipediaAPIWrapper(top_k_results=1, doc_content_chars_max=500)
wiki_tool = WikipediaQueryRun(api_wrapper=wiki_wrapper)

arxiv_wrapper = ArxivAPIWrapper(top_k_results=1, doc_content_chars_max=500)
arxiv_tool = ArxivQueryRun(api_wrapper=arxiv_wrapper)

@mcp.tool()
async def get_info(searchterm: str) -> str:
    try:
        result = wiki_tool.run(searchterm)
        return result
    except Exception as e:
        return f"Error fetching Wikipedia information: {str(e)}"
    
@mcp.tool()
async def get_research_paper(searchterm: str) -> str:
    try:
        result = arxiv_tool.run(searchterm)
        return result
    except Exception as e:
        return f"Error fetching research paper information: {str(e)}"
    
if __name__=="__main__":
    mcp.run(transport='sse') # for SSE serving
    # mcp.run(transport='stdio') for local serving

uv를 사용한 doc-server 실행

아래와 같이 위의 sever.py를 uv의 run 명령어로 실행을 하면 uv는 server.py에 구현된 기능들을 MCP client에서 사용할 수 있는 상태로 만들어 줍니다. 이 예제는 uv가 doc-server를 localhost의 포트 넘버 8000 통해서 서빙을 하고 있는 모습입니다. 

(mcp_env)$ uv run server.py
INFO:     Started server process [79863]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

doc_server.json 파일 작성

MCP 서버인 'doc-server'에 있는 기능을 이용하기 위한 MCP client를 생성하기 위해서 필요한 config Json 파일을 작성하는 예제 입니다. 이 Json 파일에 있는 내용을 MCP client 내에 dictionary로 정의해서 사용해도 동일한 결과를 얻을 수 있습니다.

{
    "mcpServers": {
        "doc_server": {
            "command": "uv",
            "url": "http://127.0.0.1:8000/sse",
            "transport": "sse"
        }
    }
}

만일 MCP 서버를 transport='stdio' 옵션으로 실행한 경우 config Json 파일을 다음과 같이 설정해야 합니다.

{
  "mcpServers": {
    "doc-server": {
      "command": "uv",
      "args": [
        "--directory",
        "Your mcp project directory.",
        "run",
        "server.py"
      ]
    }
  }
}

mcp-use를 이용한 MCP Host와 Client 코드 작성

이 코드에서는 Azure에서 서비스하는 OpenAI를 GenAI로 사용하고 mcp-use의 MCPAgent와 MCPClient를 활용하여 어떻게 MCP Host와 Client를 구성하는지를 보여주는 예제 입니다. 아래 예제가 보여주듯이 mcp-use를 활용하면 간단히 MCP Host와 Client를 구성해서 커스텀 MCP 서버 혹은 외부 MCP 서버의 기능들을 호출 할 수 있습니다.

import os
from dotenv import load_dotenv
from langchain_openai import AzureChatOpenAI
from mcp_use import MCPAgent, MCPClient

# Load environment variables
load_dotenv(".env")

# Create MCPClient from config file
client = MCPClient.from_config_file(
    "doc_server.json"
)

# Create LLM
llm = AzureChatOpenAI(
        azure_deployment=os.getenv("AZURE_OPENAI_DEPLOYMENT"),
        azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"),
        api_version=os.getenv("AZURE_OPENAI_API_VERSION"),
        verbose=False,
        temperature=0.0,
    )

# Create agent with the client
agent = MCPAgent(llm=llm, client=client, max_steps=30)

# Run the query
result = await agent.run(
    "Let me know ReciproCAM paper.",
    max_steps=30,
)
print(f"\nResult: {result}")

출력 결과

MCP Host 실행 결과

---

결론

mcp-use는 오픈소스, 다중 LLM, 다중 서버 지향 host로 Claude Desktop 의존성에서 벗어나게 해주며, UV는 초고속 패키지 관리 및 실행 환경을 제공해 재현성 있는 MCP server 배포를 가능케 합니다.

 

---

참고자료

• mcp-use GitHub
• Astral UV 문서
• Anthropic MCP 발표