로드 중
로드 중

MCP 서버의 리소스를 사용하면 일반적인 HTTP 서버의 GET 요청 핸들러와 유사하게 클라이언트에 데이터를 노출할 수 있습니다. 작업을 수행하기보다는 정보를 가져와야 하는 시나리오에 적합합니다.

리소스 이해하기

리소스는 문자열, JSON, 바이너리 파일 등 모든 유형의 데이터를 반환할 수 있는 읽기 전용 엔드포인트라고 생각하면 됩니다. 클라이언트에게 어떤 종류의 데이터를 반환하는지 힌트를 주기 위해 'mime_type'을 설정합니다.

직접 목록인 list_docs와 템플릿화된 fetch_doc, 이 두 가지 리소스를 가진 MCP 서버의 다이어그램, 아래 코드에 표시됨.

리소스는 URI(본질적으로 주소)를 통해 데이터를 노출하는 방식으로 작동합니다. 클라이언트가 데이터가 필요할 때 특정 URI가 포함된 ReadResourceRequest를 전송하면, 서버는 요청된 정보로 응답합니다.

두 가지 유형의 리소스

생성할 수 있는 리소스에는 두 가지 주요 유형이 있습니다:

  • 직접 리소스(Direct Resources) - 매개변수를 포함하지 않는 정적 URI를 가집니다(예: docs://documents)
  • 템플릿화된 리소스(Templated Resources) - URI에 매개변수를 포함합니다(예: docs://documents/{doc_id})

URI 매개변수가 없는 직접 리소스(Direct Resource)와, Python SDK가 함수에 전달하는 URI 매개변수를 가진 템플릿화된 리소스(Templated Resource)를 나란히 표시.

템플릿화된 리소스의 경우, Python SDK는 URI에서 매개변수를 자동으로 파싱하여 키워드 인자로 함수에 전달합니다. URI의 매개변수 이름이 함수의 인자 이름이 됩니다.

리소스 구현하기

@mcp.resource() 데코레이터를 사용하면 리소스를 간단하게 생성할 수 있습니다. 두 가지 유형을 모두 구현하는 방법은 다음과 같습니다:

python
@mcp.resource(
    "docs://documents",
    mime_type="application/json"
)
def list_docs() -> list[str]:
    return list(docs.keys())

@mcp.resource(
    "docs://documents/{doc_id}",
    mime_type="text/plain"
)
def fetch_doc(doc_id: str) -> str:
    if doc_id not in docs:
        raise ValueError(f"Doc with id {doc_id} not found")
    return docs[doc_id]

MCP Python SDK는 반환하는 모든 것을 자동으로 직렬화합니다. 데이터를 JSON 문자열로 수동 변환할 필요 없이 적절한 Python 데이터 구조를 반환하기만 하면 됩니다.

리소스 테스트하기

MCP Inspector 도구를 사용하여 리소스를 테스트할 수 있습니다. uv run mcp dev mcp_server.py로 서버를 시작하고 웹 인터페이스로 이동하세요.

MCP Inspector의 Resources 탭: docs://documents 리소스, fetch_doc 템플릿, 그리고 6개의 문서를 나열하는 JSON 응답.

Inspector는 직접 리소스와 템플릿화된 리소스를 구분합니다. 직접 리소스는 메인 "Resources" 섹션에 표시되고, 템플릿화된 리소스는 "Resource Templates" 아래에 표시됩니다. 리소스를 클릭하여 테스트하고 서버가 반환하는 정확한 응답 구조를 확인할 수 있습니다.

실용적인 사용 사례

리소스는 다음과 같은 경우에 이상적입니다:

  • 자동완성 데이터 제공(예: 문서 목록)
  • 파일 내용 또는 데이터베이스 레코드 가져오기
  • 구성 데이터 노출
  • 클라이언트가 필요로 하는 모든 읽기 전용 정보 제공

가장 큰 장점은 리소스를 사용하면 클라이언트가 도구나 복잡한 상호작용에 의존하지 않고도 능동적으로 데이터를 가져올 수 있다는 것입니다. 이는 사용자 참조를 기반으로 프롬프트에 콘텐츠를 자동으로 주입하고자 하는 문서 멘션과 같은 기능에 적합합니다.