시작하기

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

MCP 명세는 인가 (Authorization)에 대해 몇 가지 특정 요구사항이 있습니다:

• OAuth 2.1 IETF DRAFT
• OAuth 2.0 인가 서버 메타데이터 (RFC 8414)
• OAuth 2.0 동적 클라이언트 등록 프로토콜 (RFC 7591)

마지막 두 가지는 필수는 아니지만, 첫 번째는 안전하고 규격에 맞는 구현을 위해 반드시 필요합니다.

노트

새로운 MCP 초안에서는 RFC 8414가 인가 서버(공급자)에서 필수로 요구됩니다. 새로운 초안이 확정되면 문서를 업데이트하겠습니다.

호환되는 MCP 공급자 목록을 확인하여 사용 중인 공급자가 지원되는지 확인하세요.

MCP Auth SDK 설치하기

MCP Auth는 Python과 TypeScript 모두에서 사용할 수 있습니다. 다른 언어나 프레임워크 지원이 필요하다면 알려주세요!

Python

pip install mcpauth

또는 pipenv, poetry 등 선호하는 패키지 매니저를 사용할 수 있습니다.

Node.js

npm install mcp-auth

또는 pnpm, yarn 등 선호하는 패키지 매니저를 사용할 수 있습니다.

MCP Auth 초기화하기

첫 번째 단계는 공급자의 인가 서버 메타데이터로 MCP Auth 인스턴스를 초기화하는 것입니다. 만약 공급자가 다음 중 하나를 준수한다면:

• OAuth 2.0 인가 서버 메타데이터
• OpenID Connect Discovery

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

Python

from mcpauth import MCPAuth
from mcpauth.config import AuthServerType
from mcpauth.utils import fetch_server_config

mcp_auth = MCPAuth(
    server=fetch_server_config(
      '<auth-server-url>',
      type=AuthServerType.OIDC # 또는 AuthServerType.OAUTH
    )
)

Node.js

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

const mcpAuth = new MCPAuth({
  server: await fetchServerConfig('<auth-server-issuer>', { type: 'oidc' }), // 또는 'oauth'
});

메타데이터 URL 또는 엔드포인트를 수동으로 지정해야 하는 경우, MCP Auth 초기화의 다른 방법을 확인하세요.

메타데이터 엔드포인트 마운트하기

현재 MCP 명세를 준수하기 위해, MCP Auth는 OAuth 2.0 인가 서버 메타데이터 엔드포인트(/.well-known/oauth-authorization-server)를 MCP 서버에 마운트합니다:

Python

from starlette.applications import Starlette

app = Starlette(routes=[
    mcp_auth.metadata_route(),
])

Node.js

import express from 'express';

const app = express();
app.use(mcpAuth.delegatedRouter());

메타데이터 내의 URL은 그대로 유지되므로, 인가 서버의 역할은 전적으로 공급자에게 위임됩니다. MCP 서버에서 /.well-known/oauth-authorization-server에 접속하여 메타데이터 엔드포인트를 테스트할 수 있습니다.

왜 메타데이터 엔드포인트만 마운트하나요?

공식 SDK에서는 /authorize, /token 등 인가 엔드포인트를 마운트하는 인증 라우터를 제공하는 경우가 있습니다. 저희가 그렇게 하지 않는 이유는 다음과 같습니다:

1. 메타데이터 엔드포인트만 마운트하면, "바퀴를 다시 발명"하지 않고 공급자의 모든 기능을 최대한 활용할 수 있으며, MCP 서버에 불필요한 복잡성을 추가하지 않습니다.
2. 또한 MCP 서버의 역할을 리소스 서버로 전환하고 OAuth 2.0 보호 리소스 메타데이터 (RFC 9728)를 요구하는 작업이 진행 중입니다. 이는 MCP 서버가 더 이상 인가 로직(메타데이터 엔드포인트 포함)을 처리하지 않고, 오직 공급자에 의존하여 인증 (Authentication) 및 인가 (Authorization)를 수행하는 리소스 서버로만 동작하게 됨을 의미합니다.

노트

새로운 MCP 명세가 확정되면 MCP Auth도 이에 맞게 업데이트할 예정입니다. 그때까지는 현재 명세와 호환되는 버전을 사용하실 수 있습니다.

Bearer 인증 미들웨어 사용하기

MCP Auth 인스턴스가 초기화되면, Bearer 인증 미들웨어를 적용하여 MCP 라우트를 보호할 수 있습니다:

Python

from starlette.applications import Starlette
from starlette.middleware import Middleware
from starlette.routing import Mount
from mcpauth import MCPAuth
from mcp.server.fastmcp import FastMCP

mcp = FastMCP()
mcp_auth = MCPAuth(
  # 인증 서버 설정으로 초기화
)
bearer_auth = mcp_auth.bearer_auth_middleware(
    "jwt", required_scopes=["read", "write"]
)

app = Starlette(routes=[
    mcp_auth.metadata_route(),
    Mount(
        "/",
        app=mcp.sse_app(),
        middleware=[Middleware(bearer_auth)],
    ),
])

Node.js

import express from 'express';
import { MCPAuth } from 'mcp-auth';

const app = express();
const server = new McpServer(/* ... */);
const mcpAuth = new MCPAuth({
  /* ... */
});

app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }));

위 예시에서는 jwt 토큰 타입을 지정하고, read 및 write 스코프를 요구했습니다. JWT (JSON Web Token)를 자동으로 검증하고, 인증된 사용자 정보를 포함한 객체를 채워줍니다.

정보

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

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

MCP 구현에서 인증 정보 가져오기

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

Python

Bearer 인증 미들웨어가 적용된 후, MCP Auth는 인증된 사용자 정보를 컨텍스트 변수에 저장합니다. MCP 도구 핸들러에서 다음과 같이 접근할 수 있습니다:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP()
mcp_auth = MCPAuth(
  # 인증 서버 설정으로 초기화
)

@mcp.tool()
def add(a: int, b: int):
    """
    두 숫자를 더하는 도구입니다.
    인증된 사용자 정보는 컨텍스트에서 사용할 수 있습니다.
    """
    auth_info = mcp_auth.auth_info # 현재 컨텍스트에서 인증 정보 접근
    if auth_info:
        print(f"Authenticated user: {auth_info.claims}")
    return a + b

Node.js

도구 핸들러의 두 번째 인자는 인증된 사용자 정보를 포함하는 authInfo 객체를 포함합니다:

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

const server = new McpServer(/* ... */);
server.tool('add', { a: z.number(), b: z.number() }, async ({ a, b }, { authInfo }) => {
  // 이제 `authInfo` 객체를 사용하여 인증된 정보를 접근할 수 있습니다
});

다음 단계

계속 읽으면서 MCP Auth를 MCP 서버와 통합하는 방법과 MCP 클라이언트에서 인증 플로우를 처리하는 방법에 대한 엔드 투 엔드 예제를 확인하세요.