모델 컨텍스트 프로토콜

모델 컨텍스트 프로토콜 (Model Context Protocol, MCP)

에이전트가 다양한 외부 도구를 쓰려면, 각 서비스가 자기 방식대로 도구를 노출하면 매번 새로 통합해야 해요. **Model Context Protocol (MCP)**는 애플리케이션이 언어 모델에 도구와 컨텍스트를 제공하는 방식을 표준화하는 오픈 프로토콜이에요. 이 프로토콜을 쓰면 도구 제공 방식이 통일되므로, LangChain에서 MCP 서버의 도구를 곧바로 가져다 쓸 수 있어요. 이번 페이지에서는 그 연결 방법을 살펴볼게요.

출처: LangChain 공식 문서 — mcp

MCPAdapter란?

LangChain 에이전트는 MCP 서버에 정의된 도구를 MCPAdapter를 통해 호출해요. MCPAdapter는 서버의 도구를 발견(discover)해서, 그대로 create_agent에 전달할 수 있는 LangChain 도구로 변환합니다.

MCPAdapter는 FastMCP 위에 구축되어 있어요. 트랜스포트 추론, 프로토콜 협상, 연결 관리, 인증을 담당하죠. 이 문서 섹션은 LangChain 특유의 계층에 집중하고, 그 아래 연결 세부 사항은 FastMCP 클라이언트 문서로 연결해 줍니다.

⚠️ langchain.mcp 네임스페이스는 langchain[mcp]>=1.4.0이 필요하고 현재 베타 상태예요. 이 네임스페이스에서 import하면 프로세스당 한 번 LangChainBetaWarning 경고가 발생합니다. API는 변경될 수 있어요. v1.4.0 이전에 MCP를 썼다면 Migrate from langchain-mcp-adapters 문서를 참고하세요.

설치 (Install)

mcp extra와 함께 LangChain을 설치하면 FastMCP도 함께 딸려 옵니다.

pip install "langchain[mcp]"

빠른 시작 (Quickstart)

MCPAdapter를 열고, list_tools()로 서버의 도구를 발견한 다음, 그 컨텍스트 안에서 에이전트를 만듭니다. 도구가 클라이언트를 들고 있기 때문에 컨텍스트가 끝난 뒤에도 에이전트는 계속 사용 가능해요.

from langchain.agents import create_agent
from langchain.mcp import MCPAdapter


async def main():
    async with MCPAdapter("https://example.com/mcp") as adapter:
        tools = await adapter.list_tools()
        agent = create_agent("claude-sonnet-5", tools)
        return await agent.ainvoke({"messages": [{"role": "user", "content": "..."}]})

LangChain 문서 MCP 서버

LangChain docs MCP 서버는 https://docs.langchain.com/mcp에 있는 공개 HTTP 엔드포인트예요. 에이전트를 연결하면 커스텀 도구를 만들지 않고도 문서를 검색하고 읽을 수 있어요.

from langchain.agents import create_agent
from langchain.mcp import MCPAdapter


async def main():
    async with MCPAdapter("https://docs.langchain.com/mcp") as adapter:
        tools = await adapter.list_tools()
        agent = create_agent("claude-sonnet-5", tools)
        return await agent.ainvoke(
            {
                "messages": [
                    {
                        "role": "user",
                        "content": "How do I add short-term memory to a LangChain agent?",
                    }
                ]
            }
        )

이 docs MCP 서버는 공개되어 API 키가 필요 없어요. IDE와 코딩 에이전트(Claude Code, Cursor 등) 설정은 Use docs programmatically를 참고하세요.

서버가 노출하는 도구는 다음과 같아요.

도구	설명
`search_docs_by_lang_chain`	관련 가이드, 하우투, 예시를 위해 docs 검색
`query_docs_filesystem_docs_by_lang_chain`	가상 파일시스템을 통해 docs 읽기·검색 (`rg`, `head`, `cat` 등)
`submit_feedback`	문서 페이지의 문제 신고

트랜스포트 (Transports)

MCPAdapter는 넘겨준 대상(target)에서 트랜스포트를 추론해요. 그래서 인프로세스 서버, stdio를 통한 로컬 스크립트, 원격 URL 사이의 차이는 오직 대상 자체뿐이에요.

from pathlib import Path

from langchain.mcp import MCPAdapter

# An in-process FastMCP server: no subprocess, no socket. Ideal for tests.
in_memory = MCPAdapter(server)  # a FastMCP instance

# A script path is launched over stdio, one subprocess per adapter.
stdio = MCPAdapter(Path("weather_server.py"))

# A string must be an http(s) URL, reached over streamable HTTP.
http = MCPAdapter("https://example.com/mcp")

대상은 다음 중 하나가 될 수 있어요.

http/https URL (str) — streamable HTTP로 연결
스크립트 경로 (Path) — stdio로 서브프로세스 실행
트랜스포트 객체 (StreamableTransport) — 사전 구성된 트랜스포트 객체. Client Transports 참고
인프로세스 FastMCP 서버 — 서브프로세스나 소켓 없이 메모리에서 연결
MCPConfig dict ({"mcpServers": {...}}) — 하나의 adapter 뒤에 여러 서버. Connections 참고
사전 빌드된 fastmcp.Client — 트랜스포트, 캐싱, 프로토콜 협상에 대한 완전한 제어

str 대상은 반드시 http 또는 https URL이어야 해요. FastMCP는 문자열을 URL로 시험하기 전에 파일시스템 경로로 시험하므로, 기존 .py/.js 파일을 가리키는 문자열은 그 파일을 서브프로세스로 실행하게 돼요. 문자열은 설정이나 모델에서 가장 자주 오는 형태이기 때문에, MCPAdapter는 URL 모양과 맞지 않는 문자열을 거부합니다.

다음 단계 (Next steps)

Connections — 연결 수명주기, 다중 서버, 프로토콜 시대, 캐싱
Authentication — Bearer 토큰, OAuth 2.1, 사용자별 서버 인증
Tools — MCP 도구를 에이전트에 로드하고, 실행을 제어하며, 출력 처리

모델 컨텍스트 프로토콜