MCP 클라이언트 만들기

원문: https://modelcontextprotocol.io/docs/develop/build-client

이 튜토리얼에서는 MCP 서버에 연결되는 LLM 기반 챗봇 클라이언트를 만드는 방법을 배웁니다.

시작하기 전에 MCP 서버 만들기 튜토리얼을 먼저 살펴보면 클라이언트‑서버 통신 구조를 이해하는 데 도움이 됩니다.

Python

이 튜토리얼의 전체 코드는 여기에서 확인할 수 있습니다: mcp-client-python

시스템 요구사항

• Mac 또는 Windows
• 최신 Python 설치
• 최신 uv 설치

환경 설정

uv로 새 프로젝트를 생성합니다.

# Create project directory
uv init mcp-client
cd mcp-client

# Create virtual environment
uv venv

# Activate virtual environment
source .venv/bin/activate

# Install required packages
uv add mcp anthropic python-dotenv

# Remove boilerplate files
rm main.py

# Create our main file
touch client.py

# Create project directory
uv init mcp-client
cd mcp-client

# Create virtual environment
uv venv

# Activate virtual environment
.venv\Scripts\activate

# Install required packages
uv add mcp anthropic python-dotenv

# Remove boilerplate files
del main.py

# Create our main file
new-item client.py

API 키 설정

Anthropic Console에서 API 키를 발급받아야 합니다.

.env 파일을 만들어 저장합니다.

echo "ANTHROPIC_API_KEY=your-api-key-goes-here" > .env

.env를 .gitignore에 추가합니다.

echo ".env" >> .gitignore

클라이언트 만들기

기본 구조

import asyncio
from typing import Optional
from contextlib import AsyncExitStack

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

from anthropic import Anthropic
from dotenv import load_dotenv

load_dotenv()  # load environment variables from .env

class MCPClient:
    def __init__(self):
        # Initialize session and client objects
        self.session: Optional[ClientSession] = None
        self.exit_stack = AsyncExitStack()
        self.anthropic = Anthropic()
    # methods will go here

서버 연결 관리

async def connect_to_server(self, server_script_path: str):
    """Connect to an MCP server

    Args:
        server_script_path: Path to the server script (.py or .js)
    """
    is_python = server_script_path.endswith('.py')
    is_js = server_script_path.endswith('.js')
    if not (is_python or is_js):
        raise ValueError("Server script must be a .py or .js file")

    command = "python" if is_python else "node"
    server_params = StdioServerParameters(
        command=command,
        args=[server_script_path],
        env=None
    )

    stdio_transport = await self.exit_stack.enter_async_context(stdio_client(server_params))
    self.stdio, self.write = stdio_transport
    self.session = await self.exit_stack.enter_async_context(ClientSession(self.stdio, self.write))

    await self.session.initialize()

    # List available tools
    response = await self.session.list_tools()
    tools = response.tools
    print("\nConnected to server with tools:", [tool.name for tool in tools])

쿼리 처리 로직

async def process_query(self, query: str) -> str:
    """Process a query using Claude and available tools"""
    messages = [
        {
            "role": "user",
            "content": query
        }
    ]

    response = await self.session.list_tools()
    available_tools = [{
        "name": tool.name,
        "description": tool.description,
        "input_schema": tool.inputSchema
    } for tool in response.tools]

    # Initial Claude API call
    response = self.anthropic.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=1000,
        messages=messages,
        tools=available_tools
    )

    # Process response and handle tool calls
    final_text = []

    assistant_message_content = []
    for content in response.content:
        if content.type == 'text':
            final_text.append(content.text)
            assistant_message_content.append(content)
        elif content.type == 'tool_use':
            tool_name = content.name
            tool_args = content.input

            # Execute tool call
            result = await self.session.call_tool(tool_name, tool_args)
            final_text.append(f"[Calling tool {tool_name} with args {tool_args}]")

            assistant_message_content.append(content)
            messages.append({
                "role": "assistant",
                "content": assistant_message_content
            })
            messages.append({
                "role": "user",
                "content": [
                    {
                        "type": "tool_result",
                        "tool_use_id": content.id,
                        "content": result.content
                    }
                ]
            })

            # Get next response from Claude
            response = self.anthropic.messages.create(
                model="claude-sonnet-4-20250514",
                max_tokens=1000,
                messages=messages,
                tools=available_tools
            )

            final_text.append(response.content[0].text)

    return "\n".join(final_text)

대화 루프

async def chat_loop(self):
    """Run an interactive chat loop"""
    print("\nMCP Client Started!")
    print("Type your queries or 'quit' to exit.")

    while True:
        query = input("\nQuery: ").strip()
        if query.lower() == "quit":
            break
        if not query:
            continue
        response = await self.process_query(query)
        print("\n" + response)

정리(Cleanup)

async def cleanup(self):
    await self.exit_stack.aclose()

메인 실행

async def main():
    if len(sys.argv) < 2:
        print("Usage: python client.py <path_to_server_script>")
        return

    client = MCPClient()
    try:
        await client.connect_to_server(sys.argv[1])
        await client.chat_loop()
    finally:
        await client.cleanup()

if __name__ == "__main__":
    import sys
    asyncio.run(main())

실행

python client.py path/to/server.py

예시 화면:

C# (.NET)

C# 버전 가이드는 .NET 콘솔 앱으로 MCP 클라이언트를 만드는 방법을 다룹니다.

프로젝트 생성

dotnet new console -n QuickstartClient
cd QuickstartClient

필수 의존성 추가

dotnet add package ModelContextProtocol --prerelease
dotnet add package Anthropic.SDK
dotnet add package Microsoft.Extensions.Hosting
dotnet add package Microsoft.Extensions.AI

API 키 설정

Anthropic Console에서 API 키를 발급받아야 합니다.

dotnet user-secrets init
dotnet user-secrets set "ANTHROPIC_API_KEY" "<your key here>"

클라이언트 만들기

기본 구조 (Program.cs)

using Anthropic.SDK;
using Microsoft.Extensions.AI;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;
using ModelContextProtocol.Client;
using ModelContextProtocol.Protocol.Transport;

var builder = Host.CreateApplicationBuilder(args);

builder.Configuration
    .AddEnvironmentVariables()
    .AddUserSecrets<Program>();

위 코드는 사용자 시크릿에서 API 키를 읽을 수 있는 콘솔 앱 기본 구성을 만듭니다.

MCP 클라이언트 설정

var (command, arguments) = GetCommandAndArguments(args);

var clientTransport = new StdioClientTransport(new()
{
    Name = "Demo Server",
    Command = command,
    Arguments = arguments,
});

await using var mcpClient = await McpClient.CreateAsync(clientTransport);

var tools = await mcpClient.ListToolsAsync();
foreach (var tool in tools)
{
    Console.WriteLine($"Connected to server with tools: {tool.Name}");
}

Program.cs 하단에 다음 함수를 추가합니다.

static (string command, string[] arguments) GetCommandAndArguments(string[] args)
{
    return args switch
    {
        [var script] when script.EndsWith(".py") => ("python", args),
        [var script] when script.EndsWith(".js") => ("node", args),
        [var script] when Directory.Exists(script) || (File.Exists(script) && script.EndsWith(".csproj")) => ("dotnet", ["run", "--project", script, "--no-build"]),
        _ => throw new NotSupportedException("An unsupported server script was provided. Supported scripts are .py, .js, or .csproj")
    };
}

이 클라이언트는 명령줄 인자로 전달된 서버 스크립트에 연결하고, 연결된 서버의 도구 목록을 출력합니다.

쿼리 처리 로직

using var anthropicClient = new AnthropicClient(new APIAuthentication(builder.Configuration["ANTHROPIC_API_KEY"]))
    .Messages
    .AsBuilder()
    .UseFunctionInvocation()
    .Build();

var options = new ChatOptions
{
    MaxOutputTokens = 1000,
    ModelId = "claude-sonnet-4-20250514",
    Tools = [.. tools]
};

Console.ForegroundColor = ConsoleColor.Green;
Console.WriteLine("MCP Client Started!");
Console.ResetColor();

PromptForInput();
while(Console.ReadLine() is string query && !"exit".Equals(query, StringComparison.OrdinalIgnoreCase))
{
    if (string.IsNullOrWhiteSpace(query))
    {
        PromptForInput();
        continue;
    }

    await foreach (var message in anthropicClient.GetStreamingResponseAsync(query, options))
    {
        Console.Write(message);
    }
    Console.WriteLine();

    PromptForInput();
}

static void PromptForInput()
{
    Console.WriteLine("Enter a command (or 'exit' to quit):");
    Console.ForegroundColor = ConsoleColor.Cyan;
    Console.Write("> ");
    Console.ResetColor();
}

핵심 구성 요소

1. 클라이언트 초기화

• McpClient.CreateAsync()로 전송 방식과 서버 실행 명령을 설정

2. 서버 연결

• Python, Node.js, .NET 서버 지원
• 인자에 지정된 명령으로 서버 시작
• stdio로 서버와 통신
• 세션 초기화 후 도구 목록 획득

3. 쿼리 처리

• Microsoft.Extensions.AI 사용
• 자동 도구 호출(함수 호출) 활성화
• 사용자 입력을 서버로 전달
• 서버가 처리한 응답을 출력

클라이언트 실행

dotnet run -- path/to/server.csproj # dotnet server
dotnet run -- path/to/server.py # python server
dotnet run -- path/to/server.js # node server

dotnet run -- path/to/QuickstartWeatherServer

클라이언트 동작 흐름:

1. 지정한 서버에 연결
2. 사용 가능한 도구 목록 표시
3. 대화형 채팅 세션 시작
4. 종료 시 세션 종료

날씨 서버에 연결된 예시 화면:

다음 단계