MCP (Model Context Protocol)

개요

Model Context Protocol(MCP)은 외부 툴 서버를 시스템과 통합하기 위한 표준 프로토콜입니다. MCP 툴 서버는 채팅 완성 중 동적으로 발견하고 호출할 수 있는 툴 세트를 노출합니다. 이를 통해 핵심 코드를 수정하지 않고도 플랫폼의 기능을 확장할 수 있습니다.

인라인 파이썬 툴이나 단순 OpenAPI 통합과 달리, MCP 서버는 상태를 유지하고, 복잡한 작업을 수행하며, OAuth 2.1 Dynamic Client Registration을 포함한 인터랙티브 인증 흐름을 지원합니다.

기본 URL: https://<backend-host>/api/v1

MCP와 다른 툴 유형 비교

툴 서버 설정

MCP 서버 등록

MCP 서버는 글로벌 설정 엔드포인트를 통해 등록합니다. 각 서버 항목에는 다음이 필요합니다:

{
"url": "https://mcp-server.example.com",
"path": null,
"spec_type": "url",
"spec": null,
"type": "mcp",
"auth_type": "oauth_2.1",
"key": null,
"enable": true,
"config": { "enable": true },
"info": {
  "id": "my_mcp_server",
  "name": "My MCP Server",
  "description": "Provides custom business tools"
}
}

필드 설명:

인증 유형

없음

인증 불필요:

{
"type": "mcp",
"auth_type": "none"
}

Bearer 토큰

Bearer 토큰으로 전달되는 정적 API 키:

{
"type": "mcp",
"auth_type": "bearer",
"key": "sk-your-api-key-here"
}

세션 토큰

현재 사용자의 JWT 토큰 전달:

{
"type": "mcp",
"auth_type": "session"
}

사용자의 JWT 토큰은 MCP 서버 요청에 자동으로 첨부됩니다.

OAuth 2.0 (시스템)

사용자의 OAuth 액세스 토큰 전달 (OAuth 로그인을 사용하는 경우):

{
"type": "mcp",
"auth_type": "system_oauth"
}

OAuth 2.1 Dynamic Client Registration

MCP 전용 고급 인증. 서버가 OAuth 2.1 DCR을 자동으로 처리합니다:

{
"type": "mcp",
"auth_type": "oauth_2.1"
}

OAuth 2.1 DCR을 사용하면 서버를 처음 사용할 때 사용자에게 인증을 요청하고, 시스템이 자동으로 토큰 갱신을 처리합니다.

툴 서버 관리

GET /api/v1/configs/tool_servers

등록된 모든 툴 서버(OpenAPI 및 MCP)를 가져옵니다.

{
"TOOL_SERVER_CONNECTIONS": [
  {
    "url": "https://mcp-server.example.com",
    "path": null,
    "spec_type": "url",
    "spec": null,
    "type": "mcp",
    "auth_type": "oauth_2.1",
    "key": null,
    "enable": true,
    "config": { "enable": true },
    "info": {
      "id": "my_mcp_server",
      "name": "My MCP Server",
      "description": "Provides custom business tools"
    }
  }
]
}

POST /api/v1/configs/tool_servers

툴 서버의 전체 목록을 업데이트합니다. 전체 배열이 교체됩니다 (포함되지 않은 항목은 제거됨).

{
"TOOL_SERVER_CONNECTIONS": [
  {
    "url": "https://mcp-server.example.com",
    "type": "mcp",
    "auth_type": "oauth_2.1",
    "enable": true,
    "info": {
      "id": "my_mcp_server",
      "name": "My MCP Server",
      "description": "Provides custom business tools"
    }
  }
]
}

{
"TOOL_SERVER_CONNECTIONS": [...]
}

POST /api/v1/configs/tool_servers/verify

저장하기 전에 MCP 서버 연결을 테스트합니다.

{
"url": "https://mcp-server.example.com",
"type": "mcp",
"auth_type": "bearer",
"key": "sk-test-key"
}

{
"status": true,
"specs": [
  {
    "name": "search_documents",
    "description": "Search internal documents",
    "inputSchema": {
      "type": "object",
      "properties": {
        "query": { "type": "string" }
      }
    }
  }
]
}

툴 발견

MCP 서버가 등록되면, 해당 툴은 server:mcp: 접두어가 붙은 ID로 툴 목록에 나타납니다:

{
"id": "server:mcp:my_mcp_server",
"name": "Search Documents",
"meta": {
  "description": "Search internal documents"
},
"authenticated": true,
"created_at": 1700000000
}

OAuth 2.1 MCP 서버의 경우:

"authenticated" 필드는 현재 사용자가 서버를 인증했는지 여부를 나타냅니다:

• true — 사용자가 인증 완료; 툴 사용 가능
• false — 사용자가 아직 인증하지 않음; 사용자가 액세스를 허용할 때까지 툴 사용 불가

인증되지 않은 OAuth 서버의 툴을 호출하려고 하면, 먼저 서버를 인증하도록 리다이렉트됩니다.

채팅에서 MCP 툴 사용

MCP 툴은 채팅 완성 중 자동으로 사용 가능합니다. 커스텀 모델을 설정할 때 toolIds 배열에 MCP 서버의 툴을 포함하세요:

{
"id": "assistant_with_mcp",
"name": "Assistant with MCP Tools",
"base_model_id": "gpt-4",
"meta": {
  "toolIds": [
    "server:mcp:my_mcp_server"
  ]
}
}

채팅 완성 중 모델은 적절한 경우 등록된 MCP 툴을 호출할 수 있습니다.

OAuth 2.1 Dynamic Client Registration (DCR)

"auth_type": "oauth_2.1" 을 가진 MCP 서버의 경우, 시스템이 전체 OAuth 흐름을 처리합니다:

최초 설정:

1. 관리자가 oauth_2.1 인증으로 MCP 서버 등록
2. 백엔드가 서버의 OAuth 발견 문서를 가져옴
3. 서버가 시스템에 등록됨

사용자 인증:

1. 사용자가 MCP 툴이 필요한 메시지를 보냄
2. 시스템이 사용자가 인증되지 않음을 감지
3. 사용자가 MCP 서버의 인증 URL로 리다이렉트됨
4. 사용자가 액세스 허용
5. 백엔드가 인증 코드를 받아 액세스 토큰으로 교환
6. 툴이 사용자에게 사용 가능해짐

토큰 갱신:

• 액세스 토큰은 만료 전에 자동으로 갱신됨
• 수동 재인증 불필요

모범 사례

서버 설정

• ID 고유성: document_search_server 와 같이 고유하고 설명적인 ID 사용
• 설명: 서버가 제공하는 툴에 대한 명확한 설명 제공
• 활성화 플래그: 삭제하지 않고 서버를 일시적으로 비활성화하려면 enable: false 사용

인증

• OAuth 2.1 선호: 사용자 특정 데이터 접근의 경우 OAuth 2.1 DCR이 가장 안전한 옵션
• 세션 토큰: 시스템을 신뢰하는 내부 서비스에 사용
• Bearer 토큰: 정적 자격 증명을 사용하는 간단한 통합에 사용

모니터링

• 저장 전 확인: 배포 전에 /verify 엔드포인트로 항상 연결 테스트
• 로그 확인: 툴이 예상치 않게 실패할 경우 서버 로그 검토
• 사용자 인증 모니터링: OAuth 서버의 경우 어떤 사용자가 인증했는지 확인

예시: 문서 검색 MCP 서버 등록

POST /api/v1/configs/tool_servers

{
"TOOL_SERVER_CONNECTIONS": [
  {
    "url": "https://documents.example.com/mcp",
    "type": "mcp",
    "auth_type": "oauth_2.1",
    "enable": true,
    "info": {
      "id": "docs_mcp_server",
      "name": "Company Documents",
      "description": "Access internal company documents and policies"
    }
  }
]
}

Response:
{
"TOOL_SERVER_CONNECTIONS": [
  {
    "url": "https://documents.example.com/mcp",
    "type": "mcp",
    "auth_type": "oauth_2.1",
    "enable": true,
    "info": {
      "id": "docs_mcp_server",
      "name": "Company Documents",
      "description": "Access internal company documents and policies"
    }
  }
]
}

문제 해결

MCP 서버 접근 불가

증상: 연결 오류로 인해 확인 실패

해결 방법:

• 서버 URL이 올바르고 접근 가능한지 확인
• 방화벽 규칙이 아웃바운드 연결을 허용하는지 확인
• 직접 테스트: curl https://mcp-server.example.com/health

툴이 발견되지 않음

증상: 서버는 등록되지만 툴이 나타나지 않음

해결 방법:

• verify 엔드포인트를 실행하여 툴 발견 디버깅
• MCP 서버 로그에서 오류 확인
• 서버가 MCP 프로토콜을 올바르게 구현하는지 확인

OAuth 인증 실패

증상: 사용자가 OAuth 2.1 서버를 인증할 수 없음

해결 방법:

• 서버의 OAuth 발견 엔드포인트에 접근 가능한지 확인
• MCP 서버에서 OAuth 클라이언트 ID와 시크릿 확인
• MCP 서버에서 인증 흐름 로그 검토

툴 실행 오류

증상: 툴이 발견되지만 호출 시 실패

해결 방법:

• 사용자가 적절한 인증을 받았는지 확인 (OAuth 서버의 경우 특히)
• 툴의 입력 파라미터가 스키마와 일치하는지 확인
• 실행 오류에 대한 MCP 서버 로그 검토