모델 컨텍스트 프로토콜
원문: Koog Documentation — model-context-protocol 이 글은 Koog 공식 문서의 model-context-protocol 페이지를 한국어로 옮긴 번역본입니다. 문서 구조와 링크 의미를 유지하되, MkDocs 전용 UI 문법은 블로그에서 읽기 좋도록 정리했습니다.
모델 컨텍스트 프로토콜
MCP(Model Context Protocol)는 AI 에이전트가 일관된 인터페이스를 통해 외부 도구 및 서비스와 상호 작용할 수 있도록 하는 표준화된 프로토콜입니다.
MCP는 도구와 프롬프트를 AI 에이전트가 호출할 수 있는 API 엔드포인트로 노출합니다. 각 도구에는 특정 이름과 JSON 스키마 형식을 사용하여 입력 및 출력을 설명하는 입력 스키마가 있습니다.
Koog 프레임워크는 MCP 서버와의 통합을 제공하므로 MCP 도구를 Koog 에이전트에 통합할 수 있습니다.
프로토콜에 대해 자세히 알아보려면 Model Context Protocol 설명서를 참조하세요.
MCP 서버
MCP 서버는 모델 컨텍스트 프로토콜을 구현하고 AI 에이전트가 도구 및 서비스와 상호 작용할 수 있는 표준화된 방법을 제공합니다.
MCP Marketplace 또는 MCP DockerHub에서 즉시 사용 가능한 MCP 서버를 찾을 수 있습니다.
MCP 서버는 에이전트와 통신하기 위해 다음 전송 프로토콜을 지원합니다.
- 별도의 프로세스로 실행되는 MCP 서버와 통신하는 데 사용되는 표준 입/출력(stdio) 전송 프로토콜입니다. 예를 들어 Docker 컨테이너 또는 CLI 도구입니다.
- HTTP를 통해 MCP 서버와 통신하는 데 사용되는 SSE(서버 전송 이벤트) 전송 프로토콜(선택 사항)입니다.
Koog와의 통합
Koog 프레임워크는 MCP SDK과 agent-mcp 모듈에 제시된 추가 API 확장을 사용하여 MCP와 통합됩니다.
이 통합을 통해 Koog 에이전트는 다음을 수행할 수 있습니다.
- 다양한 전송 메커니즘(stdio, SSE)을 통해 MCP 서버에 연결합니다.
- MCP 서버에서 사용 가능한 도구를 검색합니다.
- MCP 도구를 Koog 도구 인터페이스로 변환합니다.
- 변환된 도구를 도구 레지스트리에 등록합니다.
- LLM에서 제공한 인수를 사용하여 MCP 도구를 호출합니다.
주요 구성 요소
Koog의 MCP 통합의 주요 구성 요소는 다음과 같습니다.
| 요소 | 설명 |
|---|---|
McpTool |
Koog 도구 인터페이스와 MCP SDK 사이의 브리지 역할을 합니다. |
McpToolDescriptorParser |
MCP 도구 정의를 Koog 도구 설명자 형식으로 구문 분석합니다. |
McpToolRegistryProvider |
다양한 전송 메커니즘(stdio, SSE)을 통해 MCP 서버에 연결하는 MCP 도구 레지스트리를 생성합니다. |
시작하기
1. MCP 연결 설정
Koog와 함께 MCP를 사용하려면 연결을 설정해야 합니다.
- MCP 서버를 시작합니다(프로세스, Docker 컨테이너 또는 웹 서비스로).
- 서버와 통신하기 위한 전송 메커니즘을 만듭니다.
MCP 서버는 에이전트와 통신하기 위해 stdio 및 SSE 전송 메커니즘을 지원하므로 둘 중 하나를 사용하여 연결할 수 있습니다.
스튜디오와 연결
이 프로토콜은 MCP 서버가 별도의 프로세스로 실행될 때 사용됩니다. 다음은 stdio 전송을 사용하여 MCP 연결을 설정하는 예입니다.
1// Start an MCP server (for example, as a process)2val process = ProcessBuilder("path/to/mcp/server").start()34// Create the stdio transport 5val transport = McpToolRegistryProvider.defaultStdioTransport(process)SSE와 연결
이 프로토콜은 MCP 서버가 웹 서비스로 실행될 때 사용됩니다. 다음은 SSE 전송을 사용하여 MCP 연결을 설정하는 예입니다.
1// Create the SSE transport2val transport = McpToolRegistryProvider.defaultSseTransport("http://localhost:8931")2. 도구 레지스트리 생성
MCP 연결이 완료되면 다음 방법 중 하나로 MCP 서버의 도구를 사용하여 도구 레지스트리를 생성할 수 있습니다.
- 통신을 위해 제공된 전송 메커니즘을 사용합니다. 예를 들어:
1// Create a tool registry with tools from the MCP server2val toolRegistry = McpToolRegistryProvider.fromTransport(3 transport = transport,4 serverInfo = McpServerInfo(url = "http://localhost:8931", command = "path/to/mcp/server"),5 name = "my-client",6 version = "1.0.0"7)- MCP 서버에 연결된 MCP 클라이언트를 사용합니다. 예를 들어:
1// Create a tool registry from an existing MCP client2val toolRegistry = McpToolRegistryProvider.fromClient(3 mcpClient = existingMcpClient,4 serverInfo = McpServerInfo(url = "http://localhost:8931")5)3. 에이전트와 통합
Koog 에이전트에서 MCP 도구를 사용하려면 에이전트에 도구 레지스트리를 등록해야 합니다.
1// Create an agent with the tools2val agent = AIAgent(3 promptExecutor = executor,4 strategy = strategy,5 llmModel = OpenAIModels.Chat.GPT4o,6 toolRegistry = toolRegistry7)89// Run the agent with a task that uses an MCP tool10val result = agent.run("Use the MCP tool to perform a task")사용 예
Google 지도 MCP 통합
이 예에서는 MCP를 사용하여 지리 데이터용 Google Maps 서버에 연결하는 방법을 보여줍니다.
1// Start the Docker container with the Google Maps MCP server2val process = ProcessBuilder(3 "docker", "run", "-i",4 "-e", "GOOGLE_MAPS_API_KEY=$googleMapsApiKey",5 "mcp/google-maps"6).start()78// Create the ToolRegistry with tools from the MCP server9val toolRegistry = McpToolRegistryProvider.fromProcess(process = process)1011// Create and run the agent12val agent = AIAgent(13 promptExecutor = simpleOpenAIExecutor(openAIApiToken),14 llmModel = OpenAIModels.Chat.GPT4o,15 toolRegistry = toolRegistry,16)17agent.run("Get elevation of the Jetbrains Office in Munich, Germany?")극작가 MCP 통합
이 예에서는 MCP를 사용하여 웹 자동화를 위해 Playwright 서버에 연결하는 방법을 보여줍니다.
1// Start the Playwright MCP server2val process = ProcessBuilder(3 "npx", "@playwright/mcp@latest", "--port", "8931"4).start()56// Create the ToolRegistry with tools from the MCP server7val toolRegistry = McpToolRegistryProvider.fromSseUrl("http://localhost:8931")89// Create and run the agent10val agent = AIAgent(11 promptExecutor = simpleOpenAIExecutor(openAIApiToken),12 llmModel = OpenAIModels.Chat.GPT4o,13 toolRegistry = toolRegistry,14)15agent.run("Open a browser, navigate to jetbrains.com, accept all cookies, click AI in toolbar")