Model Context Protocol

Model Context Protocol (MCP)

이 문서에서는 Pydantic AI가 Model Context Protocol(MCP)을 지원하는 방식을 알려드려요. MCP는 AI 애플리케이션이 공통 인터페이스로 외부 도구와 서비스에 연결할 수 있게 해주는 표준화된 프로토콜이에요. 에이전트가 MCP 서버에 연결해 그 도구를 사용할 수도 있고, 에이전트가 MCP 서버 안에서 사용될 수도 있어요.

출처: 문서

본문

Pydantic AI는 Model Context Protocol (MCP)을 여러 방식으로 지원해요:

에이전트가 MCP 서버에 연결해 그 도구를 사용할 수 있어요 — 아래 MCP 서버 사용하기를 참고하세요.
에이전트가 MCP 서버 안에서 사용될 수 있어요. 더 알아보기

MCP란 무엇인가요?

Model Context Protocol은 AI 애플리케이션(Pydantic AI 같은 프로그래매틱 에이전트, cursor 같은 코딩 에이전트, Claude Desktop 같은 데스크톱 애플리케이션 포함)이 공통 인터페이스를 사용해 외부 도구와 서비스에 연결할 수 있게 해주는 표준화된 프로토콜이에요.

다른 프로토콜과 마찬가지로, MCP의 꿈은 특별한 통합 없이도 다양한 애플리케이션이 서로 소통할 수 있게 되는 것이에요.

github.com/modelcontextprotocol/servers에 훌륭한 MCP 서버 목록이 있어요.

이것이 의미하는 몇 가지 예시:

Pydantic AI는 MCP 서버로 구현된 웹 검색 서비스를 사용해 심층 연구 에이전트를 구현할 수 있어요
Cursor는 Pydantic Logfire MCP 서버에 연결해 버그를 수정하는 동안 컨텍스트를 얻기 위해 로그, 트레이스, 메트릭을 검색할 수 있어요
Pydantic AI나 다른 MCP 클라이언트는 Run Python MCP 서버에 연결해 샌드박스 환경에서 임의의 Python 코드를 실행할 수 있어요

MCP 서버 사용하기

에이전트에 MCP 서버 액세스를 부여하는 권장 방법은 MCP capability를 사용하는 것이에요. 기본적으로 MCP 서버를 로컬에서 실행해서 자격 증명, 훅, 추적을 제어권 아래 두며, native=True 플래그 하나로 모델 프로바이더의 네이티브 MCP 지원에 옵트인할 수 있어서 코드 변경 없이도 같은 에이전트가 여러 프로바이더에서 동작해요:

mcp_capability.py

from pydantic_ai import Agent
from pydantic_ai.capabilities import MCP

agent = Agent(
    'openai:gpt-5.2',
    capabilities=[
        # 기본적으로 MCP 서버를 로컬에서 실행
        MCP(url='https://mcp.example.com/api'),

        # 네이티브 MCP에 옵트인 — 모델이 지원하지 않으면 로컬로 폴백
        MCP(url='https://mcp.example.com/other', native=True),
    ],
)

첫 번째 인자로 URL을 전달하면 로컬 폴백과(native=True일 때) 프로바이더 네이티브 MCP가 모두 활성화돼요. 로컬 쪽에서 local=는 모든 MCPToolset 입력을 허용해요 — URL, FastMCP 전송, 사전 빌드된 fastmcp.Client, in-process FastMCP 서버, 또는 로컬 스크립트 경로. 전체 입력 목록과 구성 옵션은 capability 문서를 참고하세요.

더 낮은 수준의 액세스가 필요하다면 — 툴셋 수명 주기를 직접 관리하거나, 하나의 MCP 서버를 여러 에이전트가 공유하거나, MCP capability가 노출하지 않는 고급 전송·클라이언트 구성을 전달해야 한다면 — toolsets=[...]을 통해 MCPToolset을 직접 사용하세요. 자세한 내용은 MCP 클라이언트 문서를 참고하세요.

로컬 폴백 없이 모델 프로바이더의 네이티브 MCP 지원만 필요하다면, MCPServerTool을 네이티브 도구로 직접 사용할 수 있어요.

Pydantic AI 에이전트로 MCP 서버를 구축하는 방법은 MCP 서버 문서를 참고하세요.

Model Context Protocol