MCP 인증

MCP 인증 (Authentication)

MCP 서버에 연결할 때, 특히 원격 서버라면 대부분 인증이 필요해요. MCPAdapter는 인증을 FastMCP에 위임합니다. 그래서 fastmcp.Client가 받아들이는 어떤 자격 증명이든 동작해요 — 정적 bearer 토큰, 전체 OAuth 2.1 흐름, 또는 어떤 httpx.Auth든요. 이번 페이지에서는 인증 방식을 하나씩 살펴볼게요.

출처: LangChain 공식 문서 — mcp/auth

⚠️ langchain.mcp 네임스페이스는 langchain[mcp]>=1.4.0이 필요하고 현재 베타 상태예요. API는 변경될 수 있어요.

방식 고르기

인증 자격 증명은 사전 빌드된 클라이언트에 전달하고, 그 클라이언트를 어댑터에 넘기는 방식으로 동작해요. 하나의 에이전트가 여러 서버에 연결할 때는 **서버별 인증(per-server)**을, 배포 환경에서는 **사용자별 인증(per-user)**을 사용해서 각 실행이 호출자를 대신해 서버에 도달하도록 해요.

Bearer 토큰 (Bearer token)

가장 단순한 경우예요. 서버가 발급한 토큰을 확인하고, 이를 Authorization: Bearer <token> 헤더에 추가합니다. 디스커버리나 브라우저, 갱신(refresh) 과정이 없어요. 토큰을 클라이언트의 auth로 전달하면 됩니다.

from fastmcp.client import Client
from langchain.mcp import MCPAdapter


async def load_tools_with_bearer(url: str, token: str) -> list:
    # `auth` accepts a bearer-token string, the literal "oauth" (full OAuth 2.1
    # with dynamic client registration), or any `httpx.Auth`.
    async with MCPAdapter(Client(url, auth=token)) as adapter:
        return await adapter.list_tools()

auth 인자는 bearer 토큰 문자열, 리터럴 "oauth", 또는 어떤 httpx.Auth든 받아들여요. MCPConfig 플릿(fleet)에서는 각 서버가 같은 키를 사용합니다.

OAuth 인증 (OAuth authentication)

자체 자격 증명을 발급하는 서버라면, 리터럴 문자열 "oauth"를 전달하면 돼요. FastMCP가 전체 OAuth 2.1 흐름을 실행합니다 — 디스커버리, 동적 클라이언트 등록, 브라우저 리다이렉트, 토큰 교환까지요. 동적 클라이언트 등록(dynamic client registration)은 클라이언트 ID를 미리 프로비저닝하는 대신, 클라이언트가 런타임에 스스로 등록한다는 뜻이에요.

async def load_tools_with_oauth(url: str) -> list:
    # "oauth" runs discovery, dynamic client registration, the browser redirect,
    # and the token exchange. Pass `OAuth(..., token_storage=...)` to persist
    # tokens across runs instead of repeating the browser step each time.
    async with MCPAdapter(Client(url, auth="oauth")) as adapter:
        return await adapter.list_tools()

기본적으로 토큰은 메모리에 저장되므로, 실행할 때마다 브라우저 단계를 반복해요. 토큰 스토어가 있는 사전 빌드된 OAuth 제공자를 전달하면 실행 간에 토큰을 영속화할 수 있어요.

from fastmcp.client import Client
from fastmcp.client.auth import OAuth

oauth = OAuth(mcp_url="https://example.com/mcp", token_storage=...)
client = Client("https://example.com/mcp", auth=oauth)

FastMCP는 흔한 ID 제공자(Auth0, WorkOS, Okta 등)용 제공자를 내장하고 있어요. 클라이언트가 실행하는 흐름은 그들 사이에서 동일합니다. 자세한 내용은 FastMCP 문서의 OAuth authentication을 참고하세요.

서버별 인증 (Per-server authentication)

하나의 에이전트가 여러 서버에 연결할 때, 각 서버는 자기만의 자격 증명이 필요할 수 있어요. 각 서버에 고유한 연결을 주려면 ClientGroup을 쓰고, 클라이언트마다 auth를 설정해서 각 서버가 독립적으로 인증되게 합니다.

from fastmcp.client.group import ClientGroup


async def load_with_per_server_auth(
    billing_url: str, docs_token: str, docs_url: str
) -> list:
    # Each server carries its own credential. A `ClientGroup` keeps one
    # connection per server, so each authenticates independently.
    group = ClientGroup(
        {
            "billing": Client(billing_url, auth="oauth"),
            "docs": Client(docs_url, auth=docs_token),
        }
    )
    async with MCPAdapter(group) as adapter:
        return await adapter.list_tools()

사용자별 인증 (Per-user authentication)

배포(deployment) 환경에서는 각 실행이 공유 자격 증명 하나가 아니라, 실행을 시작한 그 사용자로서 MCP 서버에 도달해야 해요. 이 패턴은 두 갈래로 나뉘어요.

  1. LangGraph 서버에서 호출자를 인증한다. 커스텀 인증 핸들러가 들어온 요청을 사용자 신원(identity)으로 해석하고, 각 실행은 자기 런타임에서 그 신원을 읽어요.
  2. 그 사용자를 위한 자격 증명을 발급·교환한다. 그래프 팩토리 안에서 사용자 신원을 읽고, 사용자별 토큰으로 MCP 클라이언트를 만들어 그 연결이 그 사용자의 권한을 지니게 해요.
from fastmcp.client import Client
from fastmcp.client.auth import BearerAuth

CONFIG = {
    "mcpServers": {
        "docs": { "url": "https://example.com/mcp" }
    }
}

async def make_graph(runtime):
    user = runtime.user.identity if runtime.user is not None else "anonymous"
    auth = BearerAuth(token_for(user))  # exchange for a per-user token
    async with MCPAdapter(Client(CONFIG, auth=auth)) as adapter:
        tools = await adapter.list_tools()
        return create_agent("claude-sonnet-5", tools)

프로덕션에서 token_for는 배포 환경이 이미 갖고 있는 것(세션을 사용자별 토큰으로 교환하는 OAuth 게이트웨이, 또는 신원별 authorization-code 흐름을 실행하는 fastmcp.client.auth 제공자)을 대신하는 자리표시자예요. 캐시된 응답은 검증된 신원을 키로 사용자별로 격리해서, 한 사용자가 다른 사용자의 캐시된 도구 목록을 보지 않게 해야 합니다.

함께 보기 (See also)

더 알아보기 (Learn more)