튜토리얼: 할 일 관리 앱 만들기 (Tutorial: Build a todo manager)

Python SDK 사용 가능

MCP Auth는 Python에서도 사용할 수 있습니다! 설치 및 사용법은 Python SDK 저장소를 확인하세요.

이 튜토리얼에서는 사용자 인증 (Authentication)과 인가 (Authorization)가 적용된 할 일 관리 MCP 서버를 만들어봅니다. 최신 MCP 명세를 따라, 우리의 MCP 서버는 액세스 토큰 (Access token)을 검증하고 스코프 기반 권한 (Permission)을 적용하는 OAuth 2.0 리소스 서버 (Resource Server) 역할을 하게 됩니다.

이 튜토리얼을 완료하면 다음을 얻게 됩니다:

• ✅ MCP 서버에서 역할 기반 접근 제어 (RBAC)에 대한 기본 이해
• ✅ 인가 서버가 발급한 액세스 토큰을 사용하는 리소스 서버 역할의 MCP 서버
• ✅ 할 일 작업에 대한 스코프 기반 권한 적용의 실제 구현

개요 (Overview)

이 튜토리얼에는 다음과 같은 구성 요소가 포함됩니다:

• MCP 클라이언트 (VS Code): MCP 지원이 내장된 코드 에디터로, OAuth 2.0/OIDC 클라이언트 역할을 합니다. 인가 서버와 인가 플로우를 시작하고, MCP 서버에 인증된 요청을 보내기 위해 액세스 토큰을 획득합니다.
• 인가 서버 (Authorization Server): 사용자 아이덴티티를 관리하고, 사용자를 인증 (Authentication)하며, 인가된 클라이언트에 적절한 스코프가 포함된 액세스 토큰을 발급하는 OAuth 2.1 또는 OpenID Connect 제공자입니다.
• MCP 서버 (리소스 서버): 최신 MCP 명세에 따라, MCP 서버는 OAuth 2.0 프레임워크에서 리소스 서버 역할을 합니다. 인가 서버가 발급한 액세스 토큰을 검증하고, 할 일 작업에 대해 스코프 기반 권한을 적용합니다.

이 아키텍처는 표준 OAuth 2.0 플로우를 따릅니다:

• VS Code가 사용자를 대신해 보호된 리소스에 요청
• 인가 서버가 사용자를 인증하고 액세스 토큰 발급
• MCP 서버가 토큰을 검증하고, 부여된 권한에 따라 보호된 리소스 제공

아래는 이 구성 요소들 간의 상호작용을 나타낸 고수준 다이어그램입니다:

인가 서버 이해하기 (Understand your authorization server)

스코프가 포함된 액세스 토큰 (Access tokens with scopes)

MCP 서버에서 역할 기반 접근 제어 (RBAC)를 구현하려면, 인가 서버가 스코프가 포함된 액세스 토큰을 발급할 수 있어야 합니다. 스코프는 사용자가 부여받은 권한 (Permission)을 나타냅니다.

Logto

Logto는 API 리소스 (RFC 8707: OAuth 2.0을 위한 리소스 지표) 및 역할 (Role) 기능을 통해 RBAC를 지원합니다. 설정 방법은 다음과 같습니다:

1. Logto Console (또는 자체 호스팅 Logto Console)에 로그인하세요.

2. API 리소스 및 스코프 생성:

   • "API 리소스"로 이동
   • "Todo Manager"라는 새 API 리소스 생성
   • 다음 스코프 추가:
     • create:todos: "새 할 일 항목 생성"
     • read:todos: "모든 할 일 항목 읽기"
     • delete:todos: "모든 할 일 항목 삭제"

3. 역할 생성 (관리를 쉽게 하기 위해 권장):

   • "역할"로 이동
   • "Admin" 역할을 생성하고 모든 스코프(create:todos, read:todos, delete:todos) 할당
   • "User" 역할을 생성하고 create:todos 스코프만 할당

4. 권한 할당:

   • "사용자"로 이동
   • 사용자를 선택
   • "Roles" 탭에서 역할 할당(권장)
   • 또는 "Permissions" 탭에서 직접 스코프 할당

스코프는 JWT 액세스 토큰의 scope 클레임에 공백으로 구분된 문자열로 포함됩니다.

OAuth 2.0 / OIDC

OAuth 2.0 / OIDC 제공자는 일반적으로 스코프 기반 접근 제어를 지원합니다. RBAC을 구현할 때:

1. 인가 서버에서 필요한 스코프 정의
2. 클라이언트가 인가 플로우 중에 이 스코프를 요청하도록 구성
3. 인가 서버가 부여된 스코프를 액세스 토큰에 포함하는지 확인
4. 스코프는 보통 JWT 액세스 토큰의 scope 클레임에 포함됨

스코프 정의 및 관리 방법, 액세스 토큰에 스코프가 포함되는 방식, 역할 관리 등 추가 RBAC 기능은 제공자 문서를 참고하세요.

토큰 검증 및 권한 확인 (Validating tokens and checking permissions)

최신 MCP 명세에 따르면, MCP 서버는 OAuth 2.0 프레임워크에서 리소스 서버 (Resource Server) 역할을 합니다. 리소스 서버로서 MCP 서버의 주요 책임은 다음과 같습니다:

1. 토큰 검증: MCP 클라이언트로부터 받은 액세스 토큰의 진위 및 무결성 확인
2. 스코프 적용: 액세스 토큰에서 스코프를 추출 및 검증하여 클라이언트가 수행할 수 있는 작업 결정
3. 리소스 보호: 유효한 토큰과 충분한 권한이 있는 경우에만 보호된 리소스(도구 실행) 제공

MCP 서버가 요청을 받으면 다음과 같은 검증 과정을 거칩니다:

1. Authorization 헤더에서 액세스 토큰 추출 (Bearer 토큰 형식)
2. 액세스 토큰의 서명 및 만료 검증
3. 검증된 토큰에서 스코프 및 사용자 정보 추출
4. 요청된 작업에 필요한 스코프가 토큰에 포함되어 있는지 확인

예를 들어, 사용자가 새 할 일 항목을 생성하려면 액세스 토큰에 create:todos 스코프가 포함되어 있어야 합니다. 리소스 서버의 검증 플로우는 다음과 같습니다:

동적 클라이언트 등록 (Dynamic Client Registration)

이 튜토리얼에서는 필수는 아니지만, MCP 클라이언트 등록을 인가 서버와 자동화하고 싶다면 유용할 수 있습니다. 자세한 내용은 동적 클라이언트 등록이 필요한가요?를 참고하세요.

할 일 관리 앱에서 RBAC 이해하기 (Understand RBAC in todo manager)

데모 목적상, 할 일 관리 MCP 서버에 간단한 역할 기반 접근 제어 (RBAC) 시스템을 구현합니다. 이를 통해 RBAC의 기본 원리를 쉽게 이해할 수 있습니다.

노트

이 튜토리얼은 RBAC 기반 스코프 관리를 시연하지만, 모든 인증 (Authentication) 제공자가 역할을 통해 스코프 관리를 구현하는 것은 아닙니다. 일부 제공자는 자체적인 접근 제어 및 권한 (Permission) 관리 방식을 가질 수 있습니다.

도구와 스코프 (Tools and scopes)

우리의 할 일 관리 MCP 서버는 세 가지 주요 도구를 제공합니다:

• create-todo: 새 할 일 항목 생성
• get-todos: 모든 할 일 목록 조회
• delete-todo: ID로 할 일 삭제

이 도구들에 대한 접근을 제어하기 위해 다음과 같은 스코프를 정의합니다:

• create:todos: 새 할 일 항목 생성 허용
• delete:todos: 기존 할 일 항목 삭제 허용
• read:todos: 모든 할 일 항목 목록 조회 및 검색 허용

역할과 권한 (Roles and permissions)

다음과 같이 서로 다른 접근 수준을 가진 두 가지 역할을 정의합니다:

역할	create:todos	read:todos	delete:todos
Admin	✅	✅	✅
User	✅

• User: 자신의 할 일만 생성, 조회, 삭제할 수 있는 일반 사용자
• Admin: 소유자와 관계없이 모든 할 일을 생성, 조회, 삭제할 수 있는 관리자

리소스 소유권 (Resource ownership)

위 권한 테이블은 각 역할에 명시적으로 할당된 스코프를 보여주지만, 리소스 소유권이라는 중요한 원칙이 있습니다:

• User는 read:todos 또는 delete:todos 스코프가 없어도:
  • 자신의 할 일 항목을 조회할 수 있고
  • 자신의 할 일 항목을 삭제할 수 있습니다
• Admin은 전체 권한 (read:todos, delete:todos)을 가지므로:
  • 시스템의 모든 할 일 항목을 조회할 수 있고
  • 소유자와 관계없이 모든 할 일 항목을 삭제할 수 있습니다

이는 RBAC 시스템에서 리소스 소유권이 사용자의 자신의 리소스에 대한 암묵적 권한을 부여하고, 관리 역할은 모든 리소스에 대한 명시적 권한을 받는 일반적인 패턴을 보여줍니다.

더 알아보기

RBAC 개념과 모범 사례를 더 깊이 이해하려면 Mastering RBAC: A Comprehensive Real-World Example을 참고하세요.

제공자에서 인가 구성하기 (Configure authorization in your provider)

앞서 설명한 접근 제어 시스템을 구현하려면, 인가 서버에서 필요한 스코프를 지원하도록 구성해야 합니다. 제공자별 설정 방법은 다음과 같습니다:

Logto

Logto는 API 리소스와 역할 기능을 통해 RBAC를 지원합니다. 설정 방법은 다음과 같습니다:

1. Logto Console (또는 자체 호스팅 Logto Console)에 로그인하세요.

2. API 리소스 및 스코프 생성:

   • "API 리소스"로 이동
   • "Todo Manager"라는 새 API 리소스를 생성하고, 리소스 지표 (Resource indicator)로 http://localhost:3001/ 사용
     • 중요: 리소스 지표는 MCP 서버의 URL과 일치해야 합니다. 이 튜토리얼에서는 MCP 서버가 3001 포트에서 실행되므로 http://localhost:3001/을 사용합니다. 운영 환경에서는 실제 MCP 서버 URL(예: https://your-mcp-server.example.com/)을 사용하세요.
   • 다음 스코프 생성:
     • create:todos: "새 할 일 항목 생성"
     • read:todos: "모든 할 일 항목 읽기"
     • delete:todos: "모든 할 일 항목 삭제"

3. 역할 생성 (관리를 쉽게 하기 위해 권장):

   • "Roles"로 이동
   • "Admin" 역할을 생성하고 모든 스코프(create:todos, read:todos, delete:todos) 할당
   • "User" 역할을 생성하고 create:todos 스코프만 할당
   • "User" 역할 상세 페이지에서 "General" 탭으로 이동하여 "User" 역할을 "기본 역할 (Default role)"로 설정

4. 사용자 역할 및 권한 관리:

   • 신규 사용자:
     • 기본 역할로 "User" 역할이 자동 할당됨
   • 기존 사용자:
     • "사용자 관리"로 이동
     • 사용자를 선택
     • "Roles" 탭에서 역할 할당

프로그래밍 방식 역할 관리

Logto의 Management API를 사용하여 프로그래밍 방식으로 사용자 역할을 관리할 수 있습니다. 자동화된 사용자 관리나 관리자 패널 구축 시 유용합니다.

액세스 토큰을 요청할 때, Logto는 사용자 역할 권한에 따라 토큰의 scope 클레임에 스코프를 포함합니다.

OAuth 2 / OIDC

OAuth 2.0 또는 OpenID Connect 제공자의 경우, 서로 다른 권한을 나타내는 스코프를 구성해야 합니다. 구체적인 단계는 제공자마다 다르지만 일반적으로:

1. 스코프 정의:

   • 인가 서버에서 다음을 지원하도록 구성:
     • create:todos
     • read:todos
     • delete:todos

2. 클라이언트 구성:

   • 클라이언트를 등록하거나 업데이트하여 이 스코프를 요청하도록 설정
   • 액세스 토큰에 스코프가 포함되는지 확인

3. 권한 할당:

   • 제공자 인터페이스를 통해 사용자에게 적절한 스코프 부여
   • 일부 제공자는 역할 기반 관리, 일부는 직접 스코프 할당 방식 지원
   • 권장 방식은 제공자 문서를 참고

팁

대부분의 제공자는 부여된 스코프를 액세스 토큰의 scope 클레임에 포함합니다. 형식은 일반적으로 공백으로 구분된 스코프 값 문자열입니다.

리소스 지표의 슬래시

리소스 지표에는 항상 끝에 슬래시(/)를 포함하세요. MCP 공식 SDK의 현재 버그로 인해, SDK를 사용하는 클라이언트는 인증 요청 시 리소스 식별자에 자동으로 슬래시를 추가합니다. 리소스 지표에 슬래시가 없으면 해당 클라이언트에서 리소스 검증이 실패합니다. (VS Code는 이 버그의 영향을 받지 않습니다.)

인가 서버를 구성한 후, 사용자는 부여된 스코프가 포함된 액세스 토큰을 받게 됩니다. MCP 서버는 이 스코프를 사용하여 다음을 결정합니다:

• 사용자가 새 할 일을 생성할 수 있는지 (create:todos)
• 사용자가 모든 할 일을 볼 수 있는지 (read:todos) 또는 자신의 할 일만 볼 수 있는지
• 사용자가 모든 할 일을 삭제할 수 있는지 (delete:todos) 또는 자신의 할 일만 삭제할 수 있는지

MCP 서버 설정하기 (Set up the MCP server)

MCP 공식 SDK를 사용하여 할 일 관리 MCP 서버를 만듭니다.

새 프로젝트 생성 (Create a new project)

새 Node.js 프로젝트를 설정하세요:

mkdir mcp-server
cd mcp-server
npm init -y # 또는 `pnpm init` 사용
npm pkg set type="module"
npm pkg set main="todo-manager.ts"
npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts"

노트

예제에서는 Node.js v22.6.0+에서 --experimental-strip-types 플래그로 TypeScript를 네이티브로 실행할 수 있으므로 TypeScript를 사용합니다. JavaScript를 사용할 경우 코드가 유사하니, Node.js v22.6.0 이상을 사용하세요. 자세한 내용은 Node.js 문서를 참고하세요.

MCP SDK 및 의존성 설치 (Install the MCP SDK and dependencies)

npm install @modelcontextprotocol/sdk express zod

또는 pnpm, yarn 등 원하는 패키지 매니저를 사용하세요.

MCP 서버 만들기 (Create the MCP server)

todo-manager.ts 파일을 만들고 다음 코드를 추가하세요:

// todo-manager.ts

import { z } from 'zod';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import express, { type Request, type Response } from 'express';

// MCP 서버 인스턴스 생성 팩토리 함수
// 무상태 모드에서는 각 요청마다 별도의 서버 인스턴스가 필요
const createMcpServer = () => {
  const mcpServer = new McpServer({
    name: 'Todo Manager',
    version: '0.0.0',
  });

  mcpServer.registerTool(
    'create-todo',
    {
      description: '새 할 일 생성',
      inputSchema: { content: z.string() },
    },
    async ({ content }) => {
      return {
        content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }],
      };
    }
  );

  mcpServer.registerTool(
    'get-todos',
    {
      description: '모든 할 일 목록 조회',
      inputSchema: {},
    },
    async () => {
      return {
        content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }],
      };
    }
  );

  mcpServer.registerTool(
    'delete-todo',
    {
      description: 'ID로 할 일 삭제',
      inputSchema: { id: z.string() },
    },
    async ({ id }) => {
      return {
        content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }],
      };
    }
  );

  return mcpServer;
};

// 아래는 MCP SDK 문서의 보일러플레이트 코드입니다
const PORT = 3001;
const app = express();

app.post('/', async (request: Request, response: Response) => {
  // 무상태 모드에서는 각 요청마다 별도의 transport 및 서버 인스턴스를 생성해야 함
  // 단일 인스턴스 사용 시 여러 클라이언트가 동시에 연결될 때 요청 ID 충돌 발생
  const mcpServer = createMcpServer();

  try {
    const transport = new StreamableHTTPServerTransport({
      sessionIdGenerator: undefined,
    });
    await mcpServer.connect(transport);
    await transport.handleRequest(request, response, request.body);
    response.on('close', () => {
      console.log('Request closed');
      void transport.close();
      void mcpServer.close();
    });
  } catch (error) {
    console.error('Error handling MCP request:', error);
    if (!response.headersSent) {
      response.status(500).json({
        jsonrpc: '2.0',
        error: {
          code: -32_603,
          message: 'Internal server error',
        },
        id: null,
      });
    }
  }
});

app.listen(PORT);

서버를 실행하세요:

npm start

인가 서버와 통합하기 (Integrate with your authorization server)

이 섹션을 완료하려면 다음 사항을 고려해야 합니다:

인가 서버의 발급자 (Issuer) URL

일반적으로 인가 서버의 기본 URL(예: https://auth.example.com)입니다. 일부 제공자는 https://example.logto.app/oidc와 같은 경로를 사용할 수 있으니, 제공자 문서를 확인하세요.

인가 서버 메타데이터 가져오기 방법

• 인가 서버가 OAuth 2.0 인가 서버 메타데이터 또는 OpenID Connect Discovery를 준수한다면, MCP Auth 내장 유틸리티로 메타데이터를 자동으로 가져올 수 있습니다.
• 준수하지 않는 경우, MCP 서버 설정에서 메타데이터 URL 또는 엔드포인트를 수동으로 지정해야 합니다. 제공자 문서를 참고하세요.

인가 서버에 MCP 클라이언트 등록 방법

• 인가 서버가 동적 클라이언트 등록을 지원한다면, MCP 클라이언트가 자동으로 등록됩니다.
• 지원하지 않는 경우, MCP 클라이언트를 인가 서버에 수동으로 등록해야 합니다.

토큰 요청 파라미터 이해하기

인가 서버에서 액세스 토큰을 요청할 때, 대상 리소스와 권한을 지정하는 다양한 방식이 있습니다. 주요 패턴은 다음과 같습니다:

• 리소스 지표 기반:

  • resource 파라미터로 대상 API 지정 (RFC 8707: OAuth 2.0을 위한 리소스 지표 참고)
  • 최신 OAuth 2.0 구현에서 일반적
  • 예시 요청:

    {
      "resource": "http://localhost:3001/",
      "scope": "create:todos read:todos"
    }

  • 서버는 요청된 리소스에만 바인딩된 토큰 발급

• 대상 (Audience) 기반:

  • audience 파라미터로 토큰 수신자 지정
  • 리소스 지표와 유사하지만 의미가 다름
  • 예시 요청:

    {
      "audience": "todo-api",
      "scope": "create:todos read:todos"
    }

• 순수 스코프 기반:

  • 리소스/대상 파라미터 없이 스코프만 사용
  • 전통적인 OAuth 2.0 방식
  • 예시 요청:

    {
      "scope": "todo-api:create todo-api:read openid profile"
    }

  • 권한 네임스페이스를 위해 접두사 스코프 사용
  • 단순한 OAuth 2.0 구현에서 일반적

모범 사례

• 제공자 문서에서 지원 파라미터 확인
• 일부 제공자는 여러 방식을 동시에 지원
• 리소스 지표는 대상 제한을 통해 더 나은 보안 제공
• 가능하다면 리소스 지표 사용을 권장

제공자마다 구체적인 요구사항이 다를 수 있지만, 아래 단계는 VS Code와 MCP 서버를 제공자별 설정과 함께 통합하는 과정을 안내합니다.

MCP 클라이언트를 서드파티 앱으로 등록하기 (Register MCP client as a third-party app)

Logto

Logto는 OpenID Connect 제공자로, 리소스 지표와 스코프를 지원하므로 http://localhost:3001/을 리소스 지표로 사용해 할 일 API를 안전하게 보호할 수 있습니다.

Logto는 아직 동적 클라이언트 등록을 지원하지 않으므로, MCP 클라이언트(VS Code)를 Logto 테넌트의 서드파티 앱으로 수동 등록해야 합니다:

1. Logto Console (또는 자체 호스팅 Logto Console)에 로그인
2. Applications > Third-party apps로 이동 후 "Create application" 클릭
3. Native App을 애플리케이션 유형으로 선택
4. 애플리케이션 정보 입력:
   • Application name: 예시로 "MCP Client"
   • Description: 예시로 "MCP client for VS Code"
5. VS Code용 Redirect URI 설정:

   http://127.0.0.1
   https://vscode.dev/redirect
   

6. "Save changes" 클릭
7. 앱의 Permissions 탭에서 User 섹션에, 앞서 만든 Todo Manager API 리소스의 create:todos, read:todos, delete:todos 권한 추가
8. 상단 카드에서 "App ID" 값을 확인하고 복사해둡니다.

OAuth 2.0 / OIDC

노트

이 가이드는 일반적인 OAuth 2.0 / OpenID Connect 제공자 통합 가이드입니다. OIDC는 OAuth 2.0 위에 구축되어 있으므로 단계가 유사합니다. 구체적인 내용은 제공자 문서를 참고하세요.

제공자가 동적 클라이언트 등록을 지원한다면 수동 등록을 건너뛸 수 있습니다. 그렇지 않으면 MCP 클라이언트를 수동으로 등록해야 합니다:

1. 제공자 콘솔에 로그인

2. "Applications" 또는 "Clients" 섹션에서 새 애플리케이션/클라이언트 생성

3. 클라이언트 유형이 필요하다면 "Native App" 또는 "Public client" 선택

4. 애플리케이션 생성 후, 리디렉션 URI를 설정합니다. VS Code의 경우 다음을 추가:

   http://127.0.0.1
   https://vscode.dev/redirect
   

5. 애플리케이션에 필요한 스코프/권한 구성:

   create:todos read:todos delete:todos

6. 새로 생성된 애플리케이션의 "Client ID" 또는 "Application ID"를 복사해둡니다.

MCP Auth 설정하기 (Set up MCP Auth)

먼저 MCP 서버 프로젝트에 MCP Auth SDK를 설치하세요.

pnpm

pnpm add mcp-auth

npm

npm install mcp-auth

yarn

yarn add mcp-auth

이제 MCP 서버에서 MCP Auth를 초기화해야 합니다. 보호된 리소스 모드에서는 인가 서버를 포함한 리소스 메타데이터를 구성해야 합니다.

인가 서버를 구성하는 방법은 두 가지입니다:

• 사전 페치(권장): fetchServerConfig()로 메타데이터를 미리 가져와 MCPAuth 초기화 전에 검증합니다.
• 온디맨드 디스커버리: issuer와 type만 제공하면, 최초 필요 시 메타데이터를 가져옵니다. (Cloudflare Workers 등 엣지 런타임에서 유용)

보호된 리소스 메타데이터 구성 (Configure protected resource metadata)

먼저 인가 서버의 발급자 (Issuer) URL을 확인하세요:

Logto

Logto에서는 Logto Console의 애플리케이션 상세 페이지 "Endpoints & Credentials / Issuer endpoint" 섹션에서 발급자 URL을 확인할 수 있습니다. 예시: https://my-project.logto.app/oidc

OAuth 2.0 / OIDC

OAuth 2.0 제공자의 경우:

1. 인가 서버 URL(발급자 URL 또는 base URL)을 제공자 문서에서 확인
2. 일부 제공자는 https://{your-domain}/.well-known/oauth-authorization-server에서 노출
3. 제공자 관리 콘솔의 OAuth/API 설정에서 확인

이제 MCP Auth 인스턴스를 만들 때 보호된 리소스 메타데이터를 구성하세요:

// todo-manager.ts

import { MCPAuth, fetchServerConfig } from 'mcp-auth';

const issuerUrl = '<issuer-url>'; // 인가 서버의 발급자 URL로 교체

// 이 MCP 서버의 리소스 식별자 정의
const resourceId = 'http://localhost:3001/';

// 인가 서버 구성 사전 페치(권장)
const authServerConfig = await fetchServerConfig(issuerUrl, { type: 'oidc' });

// 보호된 리소스 메타데이터로 MCP Auth 구성
const mcpAuth = new MCPAuth({
  protectedResources: {
    metadata: {
      resource: resourceId,
      authorizationServers: [authServerConfig],
      // MCP 서버가 이해하는 스코프
      scopesSupported: ['create:todos', 'read:todos', 'delete:todos'],
    },
  },
});

MCP 서버 업데이트 (Update MCP server)

거의 다 왔습니다! 이제 MCP Auth 라우트와 미들웨어 함수를 적용하고, 사용자의 스코프에 따라 할 일 관리 도구에 권한 기반 접근 제어를 구현합니다.

먼저, 보호된 리소스 메타데이터 라우트를 적용하여 MCP 클라이언트가 MCP 서버에서 예상 리소스 메타데이터를 가져올 수 있도록 합니다.

// todo-manager.ts

// 보호된 리소스 메타데이터 라우트 설정
// OAuth 클라이언트를 위한 리소스 서버 메타데이터 노출
app.use(mcpAuth.protectedResourceMetadataRouter());

다음으로, MCP Auth 미들웨어를 MCP 서버에 적용합니다. 이 미들웨어는 인증 (Authentication) 및 인가 (Authorization)를 처리하여, 인가된 사용자만 할 일 관리 도구에 접근할 수 있도록 합니다.

// todo-manager.ts

app.use(mcpAuth.protectedResourceMetadataRouter());

// MCP Auth 미들웨어 적용
app.use(
  mcpAuth.bearerAuth('jwt', {
    resource: resourceId,
    audience: resourceId,
  })
);

이제 할 일 관리 도구의 구현을 업데이트하여 MCP Auth 미들웨어를 통한 인증 (Authentication) 및 인가 (Authorization)를 활용할 수 있습니다.

도구 구현을 업데이트해봅시다.

// todo-manager.ts

// 기타 import...
import assert from 'node:assert';
import { fetchServerConfig, MCPAuth, MCPAuthBearerAuthError } from 'mcp-auth';
import { type AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';

// 다음 섹션에서 언급할 예정
import { TodoService } from './todo-service.js';

const assertUserId = (authInfo?: AuthInfo) => {
  const { subject } = authInfo ?? {};
  assert(subject, 'Invalid auth info');
  return subject;
};

const hasRequiredScopes = (userScopes: string[], requiredScopes: string[]): boolean => {
  return requiredScopes.every((scope) => userScopes.includes(scope));
};

// TodoService는 상태 공유를 위해 싱글톤으로 사용
const todoService = new TodoService();

// MCP 서버 인스턴스 생성 팩토리 함수
// 무상태 모드에서는 각 요청마다 별도의 서버 인스턴스 필요
const createMcpServer = () => {
  const mcpServer = new McpServer({
    name: 'Todo Manager',
    version: '0.0.0',
  });

  mcpServer.registerTool(
    'create-todo',
    {
      description: '새 할 일 생성',
      inputSchema: { content: z.string() },
    },
    ({ content }, { authInfo }) => {
      const userId = assertUserId(authInfo);

      /**
       * 'create:todos' 스코프가 있는 사용자만 할 일 생성 가능
       */
      if (!hasRequiredScopes(authInfo?.scopes ?? [], ['create:todos'])) {
        throw new MCPAuthBearerAuthError('missing_required_scopes');
      }

      const createdTodo = todoService.createTodo({ content, ownerId: userId });

      return {
        content: [{ type: 'text', text: JSON.stringify(createdTodo) }],
      };
    }
  );

  mcpServer.registerTool(
    'get-todos',
    {
      description: '모든 할 일 목록 조회',
      inputSchema: {},
    },
    (_params, { authInfo }) => {
      const userId = assertUserId(authInfo);

      /**
       * 'read:todos' 스코프가 있으면 모든 할 일 접근 가능 (todoOwnerId = undefined)
       * 없으면 자신의 할 일만 접근 가능 (todoOwnerId = userId)
       */
      const todoOwnerId = hasRequiredScopes(authInfo?.scopes ?? [], ['read:todos'])
        ? undefined
        : userId;

      const todos = todoService.getAllTodos(todoOwnerId);

      return {
        content: [{ type: 'text', text: JSON.stringify(todos) }],
      };
    }
  );

  mcpServer.registerTool(
    'delete-todo',
    {
      description: 'ID로 할 일 삭제',
      inputSchema: { id: z.string() },
    },
    ({ id }, { authInfo }) => {
      const userId = assertUserId(authInfo);

      const todo = todoService.getTodoById(id);

      if (!todo) {
        return {
          content: [{ type: 'text', text: JSON.stringify({ error: 'Failed to delete todo' }) }],
        };
      }

      /**
       * 사용자는 자신의 할 일만 삭제 가능
       * 'delete:todos' 스코프가 있으면 모든 할 일 삭제 가능
       */
      if (todo.ownerId !== userId && !hasRequiredScopes(authInfo?.scopes ?? [], ['delete:todos'])) {
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({ error: 'Failed to delete todo' }),
            },
          ],
        };
      }

      const deletedTodo = todoService.deleteTodo(id);

      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              message: `Todo ${id} deleted`,
              details: deletedTodo,
            }),
          },
        ],
      };
    }
  );

  return mcpServer;
};

이제 위 코드에서 사용한 "Todo 서비스"를 구현해봅시다:

todo-service.ts 파일을 생성하세요:

// todo-service.ts

type Todo = {
  id: string;
  content: string;
  ownerId: string;
  createdAt: string;
};

/**
 * 데모용 간단한 Todo 서비스.
 * 메모리 배열에 할 일 저장
 */
export class TodoService {
  private readonly todos: Todo[] = [];

  getAllTodos(ownerId?: string): Todo[] {
    if (ownerId) {
      return this.todos.filter((todo) => todo.ownerId === ownerId);
    }
    return this.todos;
  }

  getTodoById(id: string): Todo | undefined {
    return this.todos.find((todo) => todo.id === id);
  }

  createTodo({ content, ownerId }: { content: string; ownerId: string }): Todo {
    const todo: Todo = {
      id: this.genId(),
      content,
      ownerId,
      createdAt: new Date().toISOString(),
    };

    // eslint-disable-next-line @silverhand/fp/no-mutating-methods
    this.todos.push(todo);
    return todo;
  }

  deleteTodo(id: string): Todo | undefined {
    const index = this.todos.findIndex((todo) => todo.id === id);

    if (index === -1) {
      return undefined;
    }

    // eslint-disable-next-line @silverhand/fp/no-mutating-methods
    const [deleted] = this.todos.splice(index, 1);
    return deleted;
  }

  private genId(): string {
    return Math.random().toString(36).slice(2, 10);
  }
}

축하합니다! 인증 (Authentication)과 인가 (Authorization)가 적용된 완전한 MCP 서버를 성공적으로 구현했습니다!

정보

MCP Auth Node.js SDK 저장소에서 MCP 서버(OIDC 버전)의 전체 코드를 확인할 수 있습니다.

체크포인트: todo-manager 도구 실행 (Checkpoint: Run the todo-manager tools)

MCP 서버를 재시작하고 VS Code에서 연결하세요. 인증 (Authentication)과 함께 연결하는 방법은 다음과 같습니다:

1. VS Code에서 Command + Shift + P(macOS) 또는 Ctrl + Shift + P(Windows/Linux)를 눌러 명령 팔레트 열기
2. MCP: Add Server... 입력 후 선택
3. 서버 유형으로 HTTP 선택
4. MCP 서버 URL 입력: http://localhost:3001
5. OAuth 요청이 시작되면, VS Code가 App ID 입력을 요청합니다. 인가 서버에서 복사한 App ID를 입력하세요.
6. App Secret은 없으므로(공개 클라이언트), Enter를 눌러 건너뜁니다.
7. 브라우저에서 로그인 플로우를 완료하세요.

로그인 후 VS Code로 돌아오면, 이전 체크포인트에서 했던 것처럼 할 일 관리 도구를 실행하세요. 이번에는 인증된 사용자 아이덴티티로 도구를 사용할 수 있습니다. 도구의 동작은 사용자에게 할당된 역할과 권한에 따라 달라집니다:

• User(오직 create:todos 스코프만 가진 사용자)로 로그인한 경우:

  • create-todo 도구로 새 할 일 생성 가능
  • 자신의 할 일만 조회 및 삭제 가능
  • 다른 사용자의 할 일은 볼 수 없고 삭제도 불가

• Admin(모든 스코프: create:todos, read:todos, delete:todos 보유)로 로그인한 경우:

  • 새 할 일 생성 가능
  • get-todos 도구로 시스템의 모든 할 일 조회 가능
  • 누가 만들었든 모든 할 일 삭제 가능

다른 권한 수준을 테스트하려면:

1. MCP 서버 연결 해제(VS Code에서 서버 구성 제거)
2. 다른 역할/권한을 가진 사용자 계정으로 로그인
3. 동일한 도구를 다시 실행하여 권한에 따라 동작이 어떻게 달라지는지 확인

이렇게 하면 역할 기반 접근 제어 (RBAC)가 실제로 어떻게 동작하는지, 서로 다른 사용자가 시스템 기능에 대해 서로 다른 접근 권한을 갖는지 확인할 수 있습니다.

정보

MCP Auth Node.js SDK 저장소에서 MCP 서버(OIDC 버전)의 전체 코드를 확인할 수 있습니다.

마무리 (Closing notes)

축하합니다! 튜토리얼을 성공적으로 완료했습니다. 지금까지 한 일을 요약해봅시다:

• 할 일 관리 도구(create-todo, get-todos, delete-todo)가 포함된 기본 MCP 서버 설정
• 사용자와 관리자를 위한 서로 다른 권한 수준의 역할 기반 접근 제어 (RBAC) 구현
• MCP Auth를 사용해 MCP 서버를 인가 서버와 통합
• VS Code에서 사용자 인증 및 스코프가 포함된 액세스 토큰으로 도구 호출 구성

MCP Auth를 최대한 활용하려면 다른 튜토리얼과 문서도 꼭 확인해보세요.