MCP 서버를 OpenRouter와 함께 사용하는 방법

AI 개발은 빠르게 발전하고 있으며, 언어 모델과 외부 도구의 통합은 중요한 진전을 의미합니다. OpenRouter는 수많은 언어 모델에 접근하기 위한 통합된 API를 제공합니다. MCP 서버 (모델 컨텍스트 프로토콜 서버)는 이러한 모델이 외부 도구를 실행하고 실시간 데이터에 접근할 수 있도록 합니다. 이들을 결합하면 고급 AI 애플리케이션을 구축하는 데 강력한 시스템이 됩니다.

이 포스트에서는 MCP 서버를 OpenRouter와 통합하는 방법을 안내하겠습니다. 핵심 기능, 통합 과정, 그리고 실용적인 예제에 대해 배우게 됩니다.

MCP 서버와 OpenRouter 이해하기

MCP 서버를 OpenRouter와 통합하려면 먼저 각 구성 요소의 역할을 이해해야 합니다.

OpenRouter: 언어 모델에 대한 통합 접근

OpenRouter는 OpenAI, Anthropic 및 xAI와 같은 제공자의 대형 언어 모델(LLM)과의 상호 작용을 단순화하는 플랫폼입니다. OpenAI의 API 구조와 호환되는 단일 API 엔드포인트 https://openrouter.ai/api/v1/chat/completions를 제공합니다. 주요 기능은 다음과 같습니다:

• 모델 집계: 하나의 인터페이스를 통해 수백 개의 LLM에 접근합니다.
• 비용 최적화: 가용성과 가격에 따라 비용 효율적인 모델로 요청을 라우팅합니다.
• 부하 분산: 요청을 분산시켜 어떤 단일 제공자에게도 과부하가 걸리지 않도록 합니다.
• 백업: 하나의 모델이 실패할 경우 대체 모델로 전환합니다.

계속 진행하려면 OpenRouter 계정과 API 키가 필요합니다. openrouter.ai에서 계정을 만드세요.

MCP 서버: 모델 기능 확장

MCP 서버는 모델 컨텍스트 프로토콜을 구현하여 LLM이 외부 도구를 호출할 수 있도록 합니다. 독립적으로 훈련된 데이터를 기반으로 제한된 모델과는 달리, MCP 서버는 파일 디렉토리, 데이터베이스 또는 타사 API와 같은 시스템과의 실시간 상호 작용을 허용합니다. 일반적인 MCP 도구 정의에는 다음이 포함됩니다:

• 이름: 도구를 식별합니다 (예: list_files).
• 설명: 목적을 설명합니다.
• 매개변수: JSON 스키마 형식으로 입력을 지정합니다.

예를 들어, 디렉토리 파일을 나열하는 MCP 도구는 다음과 같을 수 있습니다:

{
  "name": "list_files",
  "description": "지정된 디렉토리의 파일을 나열합니다.",
  "parameters": {
    "type": "object",
    "properties": {
      "path": {"type": "string", "description": "디렉토리 경로"}
    },
    "required": ["path"]
  }
}

함께, OpenRouter는 모델을 제공하고, MCP 서버는 도구를 제공하여 강력한 AI 생태계를 형성합니다.

왜 MCP 서버를 OpenRouter와 통합해야 할까요?

이 기술들을 결합하면 여러 기술적 이점이 있습니다:

• 모델 유연성: 외부 도구 호출 기능이 있는 모든 OpenRouter 지원 LLM을 사용할 수 있습니다.
• 비용 절감: 저비용 모델과 외부 도구를 결합하여 복잡한 작업을 오프로드할 수 있습니다.
• 향상된 기능: 모델이 실시간 데이터를 가져오거나 작업을 수행할 수 있도록 합니다 (예: 파일 작업).
• 확장성: 코어 로직을 다시 작성하지 않고도 모델이나 도구를 전환할 수 있습니다.
• 미래 대비: 새로운 LLM과 도구가 등장할 때 적응할 수 있습니다.

이 통합은 현실 세계와 상호작용이 필요한 AI 시스템을 구축하는 개발자에게 이상적입니다.

단계별 통합 과정

이제 기술적인 내용을 살펴보겠습니다. MCP 서버를 OpenRouter와 통합하는 방법은 다음과 같습니다.

전제 조건

다음 사항을 확인하세요:

• OpenRouter 계정 및 API 키: openrouter.ai에서 획득합니다.
• MCP 서버: 로컬에서 실행 중 (예: http://localhost:8000)이거나 원격. 이 가이드에서는 파일 시스템 MCP 서버를 사용하겠습니다.
• Python 3.8+: requests 라이브러리와 함께 (pip install requests).
• Apidog: 선택 사항이지만 API 테스트를 위해 추천합니다. 무료로 다운로드하세요.

1단계: MCP 도구 정의 및 변환

OpenRouter는 OpenAI의 도구 호출 형식을 사용하므로 MCP 도구 정의를 변환해야 합니다. MCP 정의에서 시작하세요:

{
  "name": "list_files",
  "description": "지정된 디렉토리의 파일을 나열합니다.",
  "parameters": {
    "type": "object",
    "properties": {
      "path": {"type": "string", "description": "디렉토리 경로"}
    },
    "required": ["path"]
  }
}

형식 필드를 추가하고 함수 세부정보를 중첩하여 OpenAI 형식으로 변환합니다:

{
  "type": "function",
  "function": {
    "name": "list_files",
    "description": "지정된 디렉토리의 파일을 나열합니다.",
    "parameters": {
      "type": "object",
      "properties": {
        "path": {"type": "string", "description": "디렉토리 경로"}
      },
      "required": ["path"]
    }
  }
}

이 JSON 구조는 OpenRouter가 API 페이로드에서 기대하는 것입니다.

2단계: API 요청 구성

OpenRouter에 대한 API 요청을 준비합니다. API 키가 포함된 헤더와 모델, 메시지 및 도구와 함께하는 페이로드를 정의합니다. 다음은 Python 예제입니다:

import requests
import json

# 헤더
headers = {
    "Authorization": "Bearer your_openrouter_api_key",
    "Content-Type": "application/json"
}

# 페이로드
payload = {
    "model": "openai/gpt-4",  # 선호하는 모델로 교체
    "messages": [
        {"role": "user", "content": "현재 디렉토리의 파일을 나열하세요."}
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "list_files",
                "description": "지정된 디렉토리의 파일을 나열합니다.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "path": {"type": "string", "description": "디렉토리 경로"}
                    },
                    "required": ["path"]
                }
            }
        }
    ]
}

your_openrouter_api_key를 실제 키로 교체하세요.

3단계: 초기 API 요청 보내기

OpenRouter 엔드포인트에 POST 요청을 보냅니다:

response = requests.post(
    "https://openrouter.ai/api/v1/chat/completions",
    headers=headers,
    json=payload
)

response_data = response.json()

4단계: 도구 호출 처리

응답에 도구 호출이 포함되어 있는지 확인합니다:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_123",
            "type": "function",
            "function": {
              "name": "list_files",
              "arguments": "{\"path\": \".\"}"
            }
          }
        ]
      }
    }
  ]
}

도구 호출 세부정보를 추출합니다:

message = response_data["choices"][0]["message"]
if "tool_calls" in message:
    tool_call = message["tool_calls"][0]
    function_name = tool_call["function"]["name"]
    arguments = json.loads(tool_call["function"]["arguments"])

5단계: MCP 서버 호출하기

도구 요청을 MCP 서버에 보냅니다:

mcp_response = requests.post(
    "http://localhost:8000/call",
    json={
        "name": function_name,
        "arguments": arguments
    }
)

tool_result = mcp_response.json()["result"]  # 예: ["file1.txt", "file2.txt"]

6단계: OpenRouter에 도구 결과 반환하기

어시스턴트의 도구 호출과 결과를 메시지 이력에 추가합니다:

messages = payload["messages"] + [
    {
        "role": "assistant",
        "content": null,
        "tool_calls": [tool_call]
    },
    {
        "role": "tool",
        "tool_call_id": tool_call["id"],
        "content": json.dumps(tool_result)
    }
]

# 페이로드 업데이트
payload["messages"] = messages

# 후속 요청 보내기
final_response = requests.post(
    "https://openrouter.ai/api/v1/chat/completions",
    headers=headers,
    json=payload
)

final_output = final_response.json()["choices"][0]["message"]["content"]
print(final_output)  # 예: "파일: file1.txt, file2.txt"

7단계: 여러 도구 호출 처리

모델이 여러 도구 호출을 요구하는 경우, 프로세스를 반복합니다:

messages = payload["messages"]

while True:
    response = requests.post(
        "https://openrouter.ai/api/v1/chat/completions",
        headers=headers,
        json={"model": "openai/gpt-4", "messages": messages}
    )
    message = response.json()["choices"][0]["message"]
    
    if "tool_calls" not in message:
        print(message["content"])
        break
    
    for tool_call in message["tool_calls"]:
        function_name = tool_call["function"]["name"]
        arguments = json.loads(tool_call["function"]["arguments"])
        
        mcp_response = requests.post(
            "http://localhost:8000/call",
            json={"name": function_name, "arguments": arguments}
        )
        tool_result = mcp_response.json()["result"]
        
        messages.extend([
            {"role": "assistant", "content": null, "tool_calls": [tool_call]},
            {"role": "tool", "tool_call_id": tool_call["id"], "content": json.dumps(tool_result)}
        ])

이 방법으로 모든 도구 호출이 처리됩니다.

실제 예제: 파일 시스템 상호작용

이것을 실제 상황에 적용하여 MCP 서버로 파일을 나열해 보겠습니다.

1. 도구 정의: 이전의 list_files 도구를 사용합니다.
2. MCP 서버: http://localhost:8000에서 실행되고 있다고 가정합니다.
3. API 호출: “현재 디렉토리의 파일을 나열하세요”라는 요청을 OpenRouter에 보냅니다.
4. 응답 처리: 모델이 list_files를 호출하고 {"path": "."}를 전달합니다.
5. MCP 실행: 서버가 ["file1.txt", "file2.txt"]를 반환합니다.
6. 최종 출력: 모델이 "찾은 파일: file1.txt, file2.txt."라고 응답합니다.

다음은 전체 코드입니다:

import requests
import json

headers = {"Authorization": "Bearer your_openrouter_api_key", "Content-Type": "application/json"}
payload = {
    "model": "openai/gpt-4",
    "messages": [{"role": "user", "content": "현재 디렉토리의 파일을 나열하세요."}],
    "tools": [{
        "type": "function",
        "function": {
            "name": "list_files",
            "description": "지정된 디렉토리의 파일을 나열합니다.",
            "parameters": {
                "type": "object",
                "properties": {"path": {"type": "string", "description": "디렉토리 경로"}},
                "required": ["path"]
            }
        }
    }]
}

response = requests.post("https://openrouter.ai/api/v1/chat/completions", headers=headers, json=payload)
message = response.json()["choices"][0]["message"]

if "tool_calls" in message:
    tool_call = message["tool_calls"][0]
    function_name = tool_call["function"]["name"]
    arguments = json.loads(tool_call["function"]["arguments"])
    
    mcp_response = requests.post("http://localhost:8000/call", json={"name": function_name, "arguments": arguments})
    tool_result = mcp_response.json()["result"]
    
    messages = payload["messages"] + [
        {"role": "assistant", "content": null, "tool_calls": [tool_call]},
        {"role": "tool", "tool_call_id": tool_call["id"], "content": json.dumps(tool_result)}
    ]
    
    final_response = requests.post("https://openrouter.ai/api/v1/chat/completions", headers=headers, json={"model": "openai/gpt-4", "messages": messages})
    print(final_response.json()["choices"][0]["message"]["content"])

일반적인 문제 해결

여기 자주 발생하는 문제에 대한 해결책이 있습니다:

• 도구가 호출되지 않음: 도구 정의 구문 및 프롬프트 명확성을 확인하세요.
• 잘못된 인자: 매개변수가 JSON 스키마와 일치하는지 확인하세요.
• MCP 서버 오류: 서버 로그 및 엔드포인트(http://localhost:8000/call)를 확인하세요.
• API 인증: OpenRouter 키가 정확한지 확인하세요.

Apidog를 사용하여 API 요청과 응답을 효율적으로 디버깅하세요.

통합 확장

2000 단어를 초과하고 깊이를 더하기 위해 다음 확장을 고려하십시오:

데이터베이스 쿼리 예제

데이터베이스를 쿼리하는 MCP 도구를 정의합니다:

{
  "type": "function",
  "function": {
    "name": "query_db",
    "description": "SQL로 데이터베이스를 쿼리합니다.",
    "parameters": {
      "type": "object",
      "properties": {"sql": {"type": "string", "description": "SQL 쿼리"}},
      "required": ["sql"]
    }
  }
}

“데이터베이스에서 모든 사용자 가져오기”를 OpenRouter에 보내고 query_db 호출을 처리하여 [{"id": 1, "name": "Alice"}]와 같은 결과를 반환합니다.

오류 처리

강력한 오류 처리를 추가하세요:

try:
    mcp_response = requests.post("http://localhost:8000/call", json={"name": function_name, "arguments": arguments})
    mcp_response.raise_for_status()
except requests.RequestException as e:
    tool_result = f"오류: {str(e)}"

이는 응용 프로그램의 안정성을 보장합니다.

결론

MCP 서버를 OpenRouter와 통합하면 AI가 단일 API를 통해 외부 도구를 활용할 수 있습니다. 이 가이드에서는 설정, 도구 변환, API 호출 및 파일 시스템 상호작용과 같은 실용적 예제를 다루었습니다. 비용 절감 및 기능 향상과 같은 혜택을 통해 이 접근 방식은 기술 개발자에게 반드시 시도해야 할 것입니다.

지금 실험해 보세요. Apidog를 무료로 가져가 여기에서 API를 테스트하세요. 진행 상황을 알려주세요!