메인 콘텐츠로 건너뛰기

시작하기

MCP 인가 (Authorization) 명세 지원

이 버전은 MCP 인가 (Authorization) 명세 (버전 2025-06-18)를 지원합니다.

Python SDK 제공

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

호환되는 OAuth 2.1 또는 OpenID Connect 제공자 선택하기​

MCP 명세는 인가 (Authorization)에 대해 특정 요구 사항을 가지고 있습니다. 인가 (Authorization) 메커니즘은 기존 명세를 기반으로 하며, 보안과 상호 운용성을 보장하면서도 단순함을 유지하기 위해 선택된 일부 기능만 구현합니다:

이 명세들은 함께 작동하여 MCP 구현을 위한 안전하고 표준화된 인가 (Authorization) 프레임워크를 제공합니다.

호환 MCP 제공자 목록에서 사용 중인 제공자가 지원되는지 확인할 수 있습니다.

MCP Auth SDK 설치하기​

pnpm add mcp-auth

MCP Auth 초기화하기​

첫 번째 단계는 리소스 식별자를 정의하고, 인증 (Authentication)을 신뢰할 인가 (Authorization) 서버를 구성하는 것입니다. MCP Auth는 이제 리소스 서버 모드로 동작하며, OAuth 2.0 보호된 리소스 메타데이터 (RFC 9728)를 요구하는 최신 MCP 명세를 준수합니다.

만약 사용 중인 제공자가 다음을 준수한다면:

내장 함수를 사용하여 메타데이터를 가져오고 MCP Auth 인스턴스를 초기화할 수 있습니다:

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

// 1. 리소스 식별자를 정의하고, 신뢰할 인가 (Authorization) 서버의 설정을 가져옵니다.
const resourceIdentifier = 'https://api.example.com/notes';
const authServerConfig = await fetchServerConfig('https://auth.logto.io/oidc', { type: 'oidc' });

// 2. 리소스 서버 모드로 MCPAuth를 초기화합니다.
// `protectedResources`는 단일 객체 또는 여러 리소스에 대한 배열일 수 있습니다.
const mcpAuth = new MCPAuth({
  protectedResources: {
    metadata: {
      resource: resourceIdentifier,
      authorizationServers: [authServerConfig],
      scopesSupported: ['read:notes', 'write:notes'],
    },
  },
});

Cloudflare Workers와 같이 최상위 async fetch가 허용되지 않는 엣지 런타임을 사용하는 경우, 온디맨드 디스커버리를 대신 사용하세요:

const authServerConfig = { issuer: 'https://auth.logto.io/oidc', type: 'oidc' };

커스텀 메타데이터 URL, 데이터 변환, 수동 메타데이터 지정 등 인가 (Authorization) 서버 메타데이터를 구성하는 다른 방법은 MCP Auth 구성의 다른 방법을 참고하세요.

보호된 리소스 메타데이터 엔드포인트 마운트하기​

최신 MCP 명세를 준수하기 위해, MCP Auth는 OAuth 2.0 보호된 리소스 메타데이터 엔드포인트 (RFC 9728)를 MCP 서버에 마운트합니다. 이 엔드포인트를 통해 클라이언트는 다음을 확인할 수 있습니다:

  • 어떤 인가 (Authorization) 서버가 보호된 리소스에 대해 유효한 토큰을 발급할 수 있는지
  • 각 리소스에서 지원되는 스코프 (Scope)는 무엇인지
  • 올바른 토큰 검증을 위해 필요한 기타 메타데이터

엔드포인트 경로는 리소스 식별자의 경로 컴포넌트에 따라 자동으로 결정됩니다:

  • 경로 없음: https://api.example.com → /.well-known/oauth-protected-resource
  • 경로 있음: https://api.example.com/notes → /.well-known/oauth-protected-resource/notes

MCP 서버는 이제 리소스 서버로서 토큰을 검증하고 보호된 리소스에 대한 메타데이터를 제공하며, 인증 (Authentication) 및 인가 (Authorization)는 전적으로 외부 인가 (Authorization) 서버에 의존합니다.

SDK에서 제공하는 메서드를 사용해 이 엔드포인트를 마운트할 수 있습니다:

import express from 'express';

const app = express();

// 보호된 리소스 메타데이터를 제공하는 라우터를 마운트합니다.
// 리소스 "https://api.example.com" → 엔드포인트: /.well-known/oauth-protected-resource
// 리소스 "https://api.example.com/notes" → 엔드포인트: /.well-known/oauth-protected-resource/notes
app.use(mcpAuth.protectedResourceMetadataRouter());

Bearer 인증 (Authentication) 미들웨어 사용하기​

MCP Auth 인스턴스가 초기화되면, Bearer 인증 (Authentication) 미들웨어를 적용하여 MCP 라우트를 보호할 수 있습니다. 이제 미들웨어는 엔드포인트가 속한 리소스를 지정해야 하며, 이를 통해 올바른 토큰 검증이 가능합니다:

대상 (Audience) 검증

audience 파라미터는 안전한 토큰 검증을 위해 OAuth 2.0 명세에서 필수입니다. 하지만, 아직 리소스 식별자를 지원하지 않는 인가 (Authorization) 서버와의 호환성을 위해 현재는 선택 사항입니다. 보안을 위해 가능한 경우 항상 audience 파라미터를 포함하세요. 향후 버전에서는 명세 완전 준수를 위해 audience 검증이 필수가 될 예정입니다.

항상 스코프(Scopes)를 검증하세요

OAuth 2.0에서 스코프(Scopes)는 권한(권한) 제어의 주요 메커니즘입니다. 올바른 audience를 가진 유효한 토큰이 있다고 해서 사용자가 어떤 작업을 수행할 권한이 있다는 것을 보장하지 않습니다 — 인가 (Authorization) 서버는 빈 스코프 또는 제한된 스코프를 가진 토큰을 발급할 수 있습니다.

항상 requiredScopes를 사용하여 각 작업에 필요한 권한(권한)이 토큰에 포함되어 있는지 강제하세요. 유효한 토큰이 곧 전체 접근 권한을 의미한다고 절대 가정하지 마세요.

import express from 'express';

const app = express();

// 보호된 리소스 메타데이터를 제공하는 라우터를 마운트합니다.
app.use(mcpAuth.protectedResourceMetadataRouter());

// 리소스별 정책으로 API 엔드포인트를 보호합니다.
app.get(
  '/notes',
  mcpAuth.bearerAuth('jwt', {
    resource: resourceIdentifier,
    audience: resourceIdentifier,  // 보안을 위한 대상 (Audience) 검증 활성화
    requiredScopes: ['read:notes'],
  }),
  (req, res) => {
    // 토큰이 유효하면 `req.auth`에 클레임 (Claim)이 채워집니다.
    console.log('Auth info:', req.auth);
    res.json({ notes: [] });
  },
);

app.listen(3000);

위 예시에서는 jwt 토큰 타입과 리소스 식별자를 지정합니다. 미들웨어는 해당 리소스에 대해 구성된 신뢰할 수 있는 인가 (Authorization) 서버를 기준으로 JWT 토큰을 자동으로 검증하고, 인증된 사용자 정보를 채워줍니다.

정보

JWT (JSON Web Token)에 대해 처음 들어보셨나요? 걱정하지 마세요. 문서를 계속 읽으시면 필요할 때 설명해 드립니다. 빠른 소개는 Auth Wiki에서도 확인할 수 있습니다.

Bearer 인증 (Authentication) 구성에 대한 자세한 내용은 Bearer 인증 (Authentication) 구성하기를 참고하세요.

MCP 구현에서 인증 (Authentication) 정보 가져오기​

Bearer 인증 (Authentication) 미들웨어가 적용되면, MCP 구현 내에서 인증된 사용자(또는 아이덴티티)의 정보를 접근할 수 있습니다:

툴 핸들러의 두 번째 인자는 인증된 사용자 정보를 담고 있는 authInfo 객체를 포함합니다:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';

const server = new McpServer(/* ... */);

// 앞선 예시처럼 MCP Auth로 초기화
// ...

server.registerTool(
  'add',
  {
    description: '두 숫자를 더합니다',
    inputSchema: { a: z.number(), b: z.number() },
  },
  async ({ a, b }, { authInfo }) => {
    // 이제 `authInfo` 객체를 사용해 인증된 정보를 활용할 수 있습니다
  }
);

다음 단계​

계속 읽으면서 MCP Auth를 MCP 서버와 통합하는 엔드 투 엔드 예제와, MCP 클라이언트에서 인증 (Authentication) 플로우를 처리하는 방법을 알아보세요.