타사 AI 에이전트가 MCP 서버에 접근할 수 있도록 허용하세요

이 가이드는 mcp-auth를 사용하여 Logto를 MCP 서버와 통합하는 방법을 안내합니다. 이를 통해 표준 OpenID Connect 플로우를 사용하여 사용자를 인증하고, 그들의 아이덴티티 정보를 안전하게 가져올 수 있습니다.

다음 내용을 학습할 수 있습니다:

• MCP 서버의 인가 (Authorization) 서버로 Logto를 구성하는 방법
• MCP 서버에 “whoami” 도구를 설정하여 현재 사용자의 아이덴티티 클레임 (Claims)을 반환하는 방법
• 타사 AI 에이전트 (MCP 클라이언트)로 플로우를 테스트하는 방법

이 튜토리얼을 마치면, MCP 서버는 다음과 같은 기능을 갖추게 됩니다:

• Logto 테넌트에서 사용자를 인증 (Authentication)합니다.
• "whoami" 도구 호출 시 아이덴티티 클레임 (sub, username, name, email 등)을 반환합니다.

타사 AI 에이전트 (MCP 클라이언트)와 자체 MCP 클라이언트의 차이점

예시를 통해 살펴보겠습니다. 당신이 이메일 접근 및 자동화를 관리하는 MCP 서버를 운영하는 개발자라고 가정해봅시다.

공식 이메일 앱 (자체 MCP 클라이언트)

• 사용자가 이메일을 읽고 관리할 수 있도록 공식 이메일 앱을 제공합니다.
• 동작 방식: 공식 이메일 앱은 Logto를 사용하여 MCP 서버에 연결해 사용자를 인증 (Authentication)합니다. Alice가 로그인하면, 별도의 권한 (Permission) 화면 없이 자동으로 자신의 이메일에 접근할 수 있습니다. 신뢰할 수 있는 앱이기 때문입니다.

타사 AI 에이전트 (타사 MCP 클라이언트)

• MCP 서버를 중심으로 생태계를 구축하고자 하여, 다른 개발자가 “SmartMail AI” (이메일을 요약하고 미팅을 자동으로 예약해주는 AI 어시스턴트)를 타사 클라이언트로 통합합니다.
• 동작 방식: SmartMail AI (타사 MCP 클라이언트)는 MCP 서버를 통해 사용자 이메일에 접근하고자 합니다. Alice가 자신의 계정으로 SmartMail AI에 로그인하면:
  • SmartMail AI가 이메일과 캘린더를 읽을 수 있도록 허락하는 동의 화면 (Consent screen)이 표시됩니다.
  • Alice는 이 접근을 허용하거나 거부할 수 있습니다.
  • Alice가 동의한 데이터만 SmartMail AI와 공유되며, 명시적인 재동의 없이는 추가 데이터에 접근할 수 없습니다.

이러한 접근 (Permission) 제어는 사용자 데이터의 안전을 보장합니다. MCP 서버가 모든 데이터를 관리하더라도, SmartMail AI와 같은 타사 앱은 사용자가 명시적으로 허용한 데이터에만 접근할 수 있습니다. 이 과정은 MCP 서버의 접근 제어 구현에 의해 강제되므로 우회할 수 없습니다.

요약

클라이언트 유형	예시	동의 필요 여부	제어 주체
공식 이메일 앱	자체 이메일 애플리케이션	아니오	당신 (개발자)
타사 AI 에이전트	SmartMail AI 어시스턴트	예	다른 개발자

노트:

자체 AI 에이전트나 앱과 MCP 서버를 통합하고 싶다면, Logto로 MCP 기반 앱에 인증 (Authentication) 활성화하기 가이드를 참고하세요.

사전 준비 사항

• Logto Cloud (또는 자체 호스팅) 테넌트
• Node.js 또는 Python 환경

아키텍처 이해하기

• MCP 서버: MCP 클라이언트에 도구와 리소스를 제공하는 서버입니다.
• MCP 클라이언트: 인증 (Authentication) 플로우를 시작하고 통합을 테스트하는 데 사용되는 클라이언트입니다. 이 가이드에서는 서드파티 AI 에이전트가 클라이언트로 사용됩니다.
• Logto: OpenID Connect 제공자 (인가 (Authorization) 서버) 역할을 하며 사용자 아이덴티티를 관리합니다.

비공식 시퀀스 다이어그램은 전체 프로세스의 흐름을 보여줍니다:

노트:

MCP가 빠르게 발전하고 있기 때문에, 위 다이어그램이 최신 정보를 완전히 반영하지 않을 수 있습니다. 최신 정보는 mcp-auth 문서를 참고하세요.

Logto에서 서드파티 AI 에이전트 구성하기

서드파티 AI 에이전트가 MCP 서버에 접근할 수 있도록 하려면, Logto에서 서드파티 앱을 설정해야 합니다. 이 앱은 AI 에이전트를 대표하며, 인증 (Authentication) 및 인가 (Authorization)에 필요한 자격 증명을 획득하는 데 사용됩니다.

개발자가 Logto에서 서드파티 앱을 생성할 수 있도록 허용하기

마켓플레이스를 구축하거나 개발자가 Logto에서 서드파티 앱을 생성할 수 있도록 하려면, Logto Management API를 활용하여 프로그래밍 방식으로 서드파티 앱을 생성할 수 있습니다. 이를 통해 개발자는 자신의 애플리케이션을 등록하고 인증 (Authentication)에 필요한 자격 증명을 얻을 수 있습니다.

클라이언트 등록 프로세스를 처리할 자체 서비스를 호스팅해야 합니다. 이 서비스는 Logto Management API와 상호작용하여 개발자를 대신해 서드파티 앱을 생성합니다.

또는, Logto Console에서 직접 서드파티 앱을 수동으로 생성하여 프로세스를 익힐 수도 있습니다.

Logto에서 서드파티 앱을 수동으로 생성하기

테스트 목적이나 임시 통합을 위해 Logto Console에서 서드파티 앱을 수동으로 생성할 수 있습니다. 전체 클라이언트 등록 플로우를 구현하지 않고도 통합을 빠르게 테스트하고 싶을 때 유용합니다.

1. Logto Console에 로그인하세요.

2. 애플리케이션 → 애플리케이션 생성 → 서드파티 앱 -> OIDC로 이동하세요.

3. 앱 이름 및 기타 필수 항목을 입력한 후 애플리케이션 생성을 클릭하세요.

4. 권한 탭을 클릭한 후, 사용자 섹션에서 "추가"를 클릭하세요.

5. 열린 대화상자에서 -> 사용자 데이터 -> profile, email 권한을 선택한 후 저장을 클릭하세요.

6. 서드파티 앱에서 openid profile email 권한(스코프)을 요청하도록 스코프를 구성하세요.

   참고: OIDC를 위해서는 openid가 필수이며, profile과 email은 이전 단계에서 추가한 권한입니다.

7. 서드파티 애플리케이션의 redirect URI를 적절히 구성하세요. Logto에서도 redirect URI를 반드시 업데이트해야 합니다.

---

내부적으로, 서드파티 앱은 표준 OAuth 2.0 / OIDC 클라이언트일 뿐입니다. 즉, 여러분(또는 서드파티 개발자)은 어떤 OAuth 2.0 / OIDC 라이브러리나 프레임워크도 사용하여 Logto와 통합할 수 있습니다.

OAuth 2.0 또는 OIDC에 익숙하지 않다면, 우리의 “전통적인 웹” 빠른 시작 가이드 중 하나를 따라 시작할 수 있습니다.

유의해야 할 몇 가지 사항:

1. Logto는 현재 서드파티 앱이 “전통적인 웹” 앱이어야 합니다. 즉, 앱에는 클라이언트 시크릿을 안전하게 저장할 백엔드 서버(또는 백엔드-포-프론트엔드)가 필요합니다.
2. 대부분의 빠른 시작 가이드는 퍼스트파티 앱을 대상으로 작성되어 있지만, 서드파티 앱 통합에도 참고 자료로 사용할 수 있습니다.
3. 주요 차이점은 서드파티 앱은 동의 화면 (Consent screen)을 표시하여 사용자의 데이터 접근에 대한 명시적 권한을 요청한다는 점입니다.

더 많은 정보는 우리의 빠른 시작 가이드에서 확인할 수 있습니다.

MCP 서버 설정하기

프로젝트 생성 및 의존성 설치

Python

mkdir mcp-server
cd mcp-server
uv init # 또는 원하는 프로젝트 구조를 사용하세요
uv add "mcp[cli]" starlette uvicorn mcpauth # 또는 원하는 패키지 매니저를 사용하세요

Node.js

mkdir mcp-server
cd mcp-server
npm init -y
npm install @modelcontextprotocol/sdk express mcp-auth # 또는 원하는 패키지 매니저를 사용하세요

Logto로 MCP 인증 구성하기

앞서 복사한 발급자 (Issuer) 엔드포인트를 <your-logto-issuer-endpoint>로 교체하세요.

Python

whoami.py에서:

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

auth_issuer = '<your-logto-issuer-endpoint>'
auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC)
mcp_auth = MCPAuth(server=auth_server_config)

Node.js

whoami.js에서:

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

const authIssuer = '<your-logto-issuer-endpoint>';
const mcpAuth = new MCPAuth({
  server: await fetchServerConfig(authIssuer, { type: 'oidc' }),
});

토큰 검증 구현하기

액세스 토큰 (Access token)을 검증하고 사용자 정보를 가져오기 위해, 다음과 같이 액세스 토큰 검증을 구현해야 합니다:

Python

import requests
from mcpauth.types import AuthInfo

def verify_access_token(token: str) -> AuthInfo:
    endpoint = auth_server_config.metadata.userinfo_endpoint
    response = requests.get(
        endpoint,
        headers={"Authorization": f"Bearer {token}"},
    )
    response.raise_for_status()
    data = response.json()
    return AuthInfo(
        token=token,
        subject=data.get("sub"),
        issuer=auth_server_config.metadata.issuer,
        claims=data,
    )

Node.js

const verifyToken = async (token) => {
  const { userinfoEndpoint, issuer } = mcpAuth.config.server.metadata;
  const response = await fetch(userinfoEndpoint, {
    headers: { Authorization: `Bearer ${token}` },
  });
  if (!response.ok) throw new Error('Token verification failed');
  const userInfo = await response.json();
  return {
    token,
    issuer,
    subject: userInfo.sub,
    claims: userInfo,
  };
};

"whoami" 도구 구현하기

이제, 클라이언트가 보낸 액세스 토큰 (Access token)으로 userinfo 엔드포인트를 요청하여 현재 사용자의 아이덴티티 클레임 (Claims)을 반환하는 "whoami" 도구를 구현해봅시다.

노트:

현재 SDK 버전에서 Streamable HTTP 트랜스포트에 대한 공식 지원이 없으므로 예제에서는 SSE 트랜스포트를 사용합니다. 이론적으로는 HTTP 호환 트랜스포트라면 어떤 것이든 사용할 수 있습니다.

Python

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

mcp = FastMCP("WhoAmI")

@mcp.tool()
def whoami() -> dict:
    """
    현재 사용자의 아이덴티티 정보를 반환합니다.
    """
    return (
        mcp_auth.auth_info.claims
        if mcp_auth.auth_info
        else {"error": "Not authenticated"}
    )

bearer_auth = Middleware(mcp_auth.bearer_auth_middleware(verify_access_token))
app = Starlette(
    routes=[
        mcp_auth.metadata_route(),  # OIDC 메타데이터를 디스커버리용으로 제공
        Mount('/', app=mcp.sse_app(), middleware=[bearer_auth]),
    ],
)

서버 실행:

uvicorn whoami:app --host 0.0.0.0 --port 3001

Node.js

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

// MCP 서버 생성 및 whoami 도구 등록
const server = new McpServer({ name: 'WhoAmI', version: '0.0.0' });
server.tool('whoami', ({ authInfo }) => ({
  content: [
    { type: 'text', text: JSON.stringify(authInfo?.claims ?? { error: 'Not authenticated' }) },
  ],
}));

// Express 앱 & MCP Auth 미들웨어
const app = express();
app.use(mcpAuth.delegatedRouter());
app.use(mcpAuth.bearerAuth(verifyToken));

// SSE 트랜스포트 (SDK 문서 참고)
const transports = {};
app.get('/sse', async (_req, res) => {
  const transport = new SSEServerTransport('/messages', res);
  transports[transport.sessionId] = transport;
  res.on('close', () => delete transports[transport.sessionId]);
  await server.connect(transport);
});
app.post('/messages', async (req, res) => {
  const sessionId = String(req.query.sessionId);
  const transport = transports[sessionId];
  if (transport) await transport.handlePostMessage(req, res, req.body);
  else res.status(400).send('No transport found for sessionId');
});

app.listen(3001);

서버 실행:

node whoami.js

통합 테스트하기

1. MCP 서버를 시작하세요.
2. AI 에이전트를 시작하세요.
3. 클라이언트에서 whoami 도구를 호출하여 현재 사용자의 아이덴티티 클레임 (Claims)을 가져옵니다.
4. 클라이언트는 401 Unauthorized 응답을 처리하고 사용자를 Logto로 리디렉션하여 인증 (Authentication)해야 합니다.
5. 인증 (Authentication)에 성공하면, 클라이언트는 액세스 토큰 (Access token)을 받아 MCP 서버에 요청을 보냅니다.
6. 클라이언트는 액세스 토큰 (Access token)을 사용하여 MCP 서버에서 아이덴티티 클레임 (Claims)을 가져올 수 있어야 합니다.

Python

전체 MCP 서버 코드는 mcp-auth/python 저장소에서 확인할 수 있습니다.

Node.js

전체 MCP 서버 코드는 mcp-auth/js 저장소에서 확인할 수 있습니다.