MCPToolKit - 프로덕션에 바로 적용 가능한 MCP 서버 프레임워크

우리가 해결하는 문제들

1. 프로덕션 환경에서 MCP 서버 확장

표준 FastMCP 프레임워크는 프로덕션 환경에서 다음과 같은 심각한 문제에 직면합니다.

상태 관리 : 기존 FastMCP 서버는 메모리에 상태를 유지하므로 수평 확장이 어렵습니다.
서버리스 제한 사항 : 서버리스 환경에는 상태 비저장 아키텍처가 필요하며 FastMCP는 이를 위해 설계되지 않았습니다.
다중 테넌트 지원 : 동일한 서버에서 여러 테넌트를 실행하려면 복잡한 세션 관리가 필요합니다.

2. 위임된 OAuth 지원

MCP 서버에 대한 인증을 관리하는 것은 복잡합니다.

도구 수준 인증 : 사용자는 도구에 필요한 경우에만 인증을 받아야 합니다.
타사 통합 : Notion, Slack 등의 서비스에 대한 OAuth 지원에는 복잡한 토큰 관리가 필요합니다.
보안 : 보안을 유지하면서 여러 인증 흐름을 관리하는 것은 어렵습니다.

우리의 솔루션

MCPToolKit은 FastMCP와의 완벽한 호환성을 유지하면서 이러한 문제를 해결하는 프로덕션 지원 프레임워크를 제공합니다. 작동 방식은 다음과 같습니다.

지엑스피1

이 아키텍처 다이어그램은 MCPToolKit이 프로덕션에 적합한 MCP 서버를 어떻게 구현하는지 보여줍니다.

LLM 클라이언트 (예: Claude, ChatGPT, Cursor)는 MCP 서버에 요청을 시작합니다. 이러한 클라이언트는 MCP 도구와 상호 작용해야 하는 모든 애플리케이션일 수 있습니다.
로드 밸런서는 들어오는 요청을 여러 MCP 서버 인스턴스로 분산시켜 수평적 확장과 높은 가용성을 구현합니다.
MCP 서버 인스턴스 (1~N)는 도구 실행 및 리소스 액세스를 처리합니다. 각 인스턴스는 다음을 수행합니다.
- 세션 지속성을 위해 자체 Redis 상태를 유지합니다.
- 요청을 독립적으로 처리할 수 있습니다
- 동일한 코드베이스와 구성을 공유합니다.
- 수요에 따라 수평적으로 확장 가능
Redis는 중앙 상태 저장소 역할을 하며 다음을 제공합니다.
- 서버 재시작 시 세션 상태 지속성
- OAuth 토큰 저장 및 관리
- 서버 인스턴스 간 공유 상태
- 상태 비저장 서버 인스턴스를 활성화합니다.
MCP 인증 서버 (분홍색으로 강조 표시)는 모든 OAuth 관련 작업을 관리합니다.
- 보안 인증을 위해 PKCE를 사용하여 OAuth 2.1을 구현합니다.
- 토큰 발급 및 새로 고침을 처리합니다.
- 동의 흐름을 관리합니다
- 모든 서버 인스턴스에 대한 OAuth 논리를 중앙화합니다.
OAuth 제공자 (예: Notion, Slack)는 사용자가 인증할 수 있는 타사 서비스입니다. 인증 서버는 이러한 연결을 안전하게 관리합니다.

이 아키텍처는 다음을 가능하게 합니다.

상태 비저장 서버 인스턴스를 통한 진정한 수평 확장
중앙화된 OAuth 관리
여러 서버 인스턴스를 통한 고가용성
안전한 토큰 관리
세션 전반에 걸쳐 일관된 사용자 경험

FastMCP에서 마이그레이션

FastMCP에서 MCPToolKit으로 마이그레이션하는 것은 간단합니다. 기존 FastMCP 서버를 업데이트하는 방법은 다음과 같습니다.

# Before (FastMCP)
- from mcp.server.fastmcp import FastMCP
- 
- # Create an MCP server
- mcp = FastMCP("Demo")

# After (MCPToolKit)
+ from mcptoolkit import MCPToolKit
+ import os
+ 
+ # Create a production-ready MCP server
+ mcp = MCPToolKit(
+     name="Demo",
+     redis_url=os.environ["REDIS_URL"]  # Required: Set REDIS_URL in your environment
+ )

# Your tools and resources remain exactly the same
@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b

@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """Get a personalized greeting"""
    return f"Hello, {name}!"

마이그레이션에는 몇 가지 간단한 변경 사항만 필요합니다.

import 문 변경
REDIS_URL 환경 변수를 설정합니다(프로덕션에 필요)
그게 전부입니다! 기존 도구, 리소스 및 프롬프트는 모두 이전과 동일하게 작동합니다.

로컬 개발의 경우 환경 변수를 설정할 수 있습니다.

export REDIS_URL="redis://localhost:6379/0"

서버리스 배포의 경우 배포 구성도 업데이트해야 합니다.

# Before (FastMCP)
- # api/index.py
- from mcp.server.fastmcp import FastMCP
- 
- mcp = FastMCP("Demo")
- app = mcp.create_fastapi_app()

# After (MCPToolKit)
+ # api/index.py
+ from mcptoolkit.vercel import create_vercel_app
+ import os
+ 
+ app = create_vercel_app(
+     name="Demo",
+     redis_url=os.environ["REDIS_URL"]  # Required: Set REDIS_URL in your environment
+ )

주요 특징:

Redis 지원 상태 : 세션 상태는 서버 재시작 및 함수 호출 시에도 유지됩니다.
서버리스 준비 : Vercel, AWS Lambda 및 기타 서버리스 플랫폼용으로 설계됨
수평 확장 : 상태 지속성을 통해 진정한 수평 확장이 가능해집니다.
다중 테넌트 지원 : 여러 사용자가 격리된 세션을 통해 동일한 엔드포인트에 연결할 수 있습니다.

2. 위임된 OAuth 지원

from mcptoolkit import MCPToolKit, requires_auth
from mcptoolkit.auth.providers import NotionProvider, SlackProvider

# Define default scopes for each provider
default_notion_scopes = [
    "read:database",
    "write:page",
    "read:page"
]

default_slack_scopes = [
    "channels:read",
    "chat:write",
    "reactions:write"
]

server = MCPToolKit(name="Auth Server")

@server.tool()
@requires_auth(provider=NotionProvider(
    scopes=default_notion_scopes,
    consent_required=True  # Require explicit user consent
))
def notion_search(query: str, ctx: Context) -> str:
    # Access authenticated Notion client with specific scopes
    notion = ctx.get_oauth_client("notion")
    return notion.search(query)

@server.tool()
@requires_auth(provider=SlackProvider(
    scopes=default_slack_scopes,
    consent_required=True
))
def slack_message(channel: str, message: str, ctx: Context) -> str:
    # Access authenticated Slack client with specific scopes
    slack = ctx.get_oauth_client("slack")
    return slack.post_message(channel, message)

주요 특징:

지연 인증 : 사용자는 도구에서 요구할 때만 인증합니다.
공급자 지원 : 일반적인 공급자(Notion, Slack 등)에 대한 기본 지원이 제공됩니다.
토큰 관리 : 토큰 자동 새로 고침 및 저장
보안 : 안전한 토큰 저장 및 전송
세분화된 범위 : OAuth 권한에 대한 세분화된 제어
동의 관리 : 논리적 권한 그룹화를 통한 사용자 친화적 동의 화면
인간 참여형 : 고위험 작업에 대한 선택적 승인 요구 사항

OAuth 흐름

MCPToolKit은 PKCE를 사용하여 안전한 OAuth 2.1 흐름을 구현합니다.

LLM 클라이언트가 MCP 서버에 요청을 시작합니다.
서버는 401 Unauthorized로 응답하고 링크를 리디렉션합니다.
사용자는 OAuth 공급자에 로그인하고 요청된 범위를 부여합니다.
서버는 클라이언트에게 인증 코드를 반환합니다.
클라이언트는 코드를 액세스 + 새로 고침 토큰으로 교환합니다.
토큰은 후속 요청에 사용됩니다.
MCP 서버는 타사 서비스를 호출합니다.

권한 부여 서버 아키텍처

MCPToolKit은 권한 부여 서버에 대해 두 가지 배포 모델을 지원합니다.

내장된 권한 부여 서버
- MCP 서버는 ID 공급자와 신뢰 당사자 역할을 모두 수행합니다.
- 로그인, 동의, 토큰 발급을 직접 처리합니다.
- 토큰 수명, 새로 고침 논리 및 취소를 관리합니다.
- 독립형 애플리케이션에 가장 적합
외부 인증 서버
- MCP 서버는 신뢰 당사자 역할을 합니다.
- OAuth 흐름을 외부 서비스(예: Stytch)에 위임합니다.
- 도구 수준 액세스 제어에 중점을 둡니다.
- 기존 ID 인프라와 통합하는 데 가장 적합

두 모델 모두 다음을 지원합니다.

PKCE를 사용한 OAuth 2.1
동적 클라이언트 등록
권한 부여 서버 메타데이터(RFC 8414)
리소스/작업 기반 사용자 정의 범위
최종 사용자 동의 관리
공급자별 세분화된 범위 정의
조직 수준의 가시성 및 제어
묵시적 권한(사용자는 자신이 가지고 있는 권한만 부여할 수 있음)

동의 및 액세스 관리

MCPToolKit은 포괄적인 동의 및 액세스 관리를 제공합니다.

조직 수준 가시성 : 조직 전체에서 승인된 모든 연결된 앱을 확인하세요.
세분화된 권한 : 어떤 멤버가 액세스를 허용했는지, 어떤 범위를 승인했는지 확인하세요.
액세스 관리 : 언제든지 특정 사용자 또는 앱에 대한 액세스 권한을 취소합니다.
사용자 친화적 동의 : 논리적 그룹으로 RBAC 권한 표시
묵시적 권한 : 사용자는 앱에 자신이 가진 것과 동일한 권한만 부여할 수 있습니다.
인간 참여형 : 고위험 작업에 대해 인간의 승인이 필요합니다.

고위험 행동 보호

@server.tool()
@requires_auth(provider=NotionProvider(
    scopes=["delete:database"],
    human_approval_required=True  # Require explicit human approval
))
def delete_database(database_id: str, ctx: Context) -> str:
    # This action will require explicit human approval
    notion = ctx.get_oauth_client("notion")
    return notion.delete_database(database_id)

건축학

배포 옵션

쿠버네티스

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-server
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: mcp-server
        image: your-mcp-server
        env:
        - name: REDIS_URL
          valueFrom:
            secretKeyRef:
              name: redis-credentials
              key: url

서버리스(Vercel)

# api/index.py
from mcptoolkit.vercel import create_vercel_app

app = create_vercel_app(
    name="Serverless MCP",
    redis_url=os.environ.get("REDIS_URL")
)

빠른 시작

MCPToolKit 설치:

pip install mcp-python-sdk

서버를 생성하세요:

from mcptoolkit import MCPToolKit, requires_auth

server = MCPToolKit(
    name="My Production Server",
    redis_url="redis://localhost:6379/0"
)

@server.tool()
def public_tool() -> str:
    return "This tool doesn't require auth"

@server.tool()
@requires_auth(provider="notion")
def notion_tool() -> str:
    return "This tool requires Notion auth"

원하는 플랫폼(Kubernetes, Vercel 등)에 배포하세요.

요구 사항

파이썬 3.9 이상
Redis 인스턴스(세션 상태 지속성용)
OAuth 공급자 자격 증명(위임된 인증을 사용하는 경우)

특허

MCP Python SDK와 동일합니다.

FastMCP Multi-Tenancy

Integrations

MCPToolKit - 프로덕션에 바로 적용 가능한 MCP 서버 프레임워크

우리가 해결하는 문제들

1. 프로덕션 환경에서 MCP 서버 확장

2. 위임된 OAuth 지원

우리의 솔루션

FastMCP에서 마이그레이션

2. 위임된 OAuth 지원

OAuth 흐름

권한 부여 서버 아키텍처

동의 및 액세스 관리

고위험 행동 보호

건축학

배포 옵션

쿠버네티스

서버리스(Vercel)

빠른 시작

요구 사항

특허