로드 중
로드 중

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

리소스 이해하기

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

MCP 서버가 보유한 두 개의 리소스, 즉 직접 리소스인 list_docs와 템플릿 리소스인 fetch_doc을 나타낸 다이어그램으로, 아래 코드에서 확인할 수 있습니다.

리소스는 클라이언트가 요청할 수 있는 URI(URL과 유사)를 정의하는 방식으로 작동합니다. 클라이언트가 데이터를 필요로 할 때 특정 URI와 함께 ReadResourceRequest를 전송하면, 서버는 해당 데이터를 담은 ReadResourceResult로 응답합니다.

두 가지 유형의 리소스

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

  • 직접 리소스(Direct Resources) - 매개변수를 포함하지 않는 정적 URI를 가집니다(예: "docs://documents")
  • 템플릿 리소스(Templated Resources) - URI에 매개변수를 포함하며, 이 매개변수는 파싱되어 함수로 전달됩니다(예: "docs://documents/{doc_id}")

URI 매개변수가 없는 직접 리소스와, Python SDK가 URI 매개변수를 함수로 전달하는 템플릿 리소스를 나란히 보여주는 그림.

템플릿 리소스의 경우, Python SDK가 URI에서 매개변수를 자동으로 파싱하여 함수에 키워드 인수로 전달합니다. URI의 매개변수 이름은 함수의 매개변수 이름과 정확히 일치해야 합니다.

리소스 생성하기

두 가지 유형의 리소스를 모두 구현하는 방법은 다음과 같습니다:

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 객체를 그대로 반환하면 SDK가 변환을 처리해 줍니다.

리소스 테스트하기

MCP Inspector를 사용하여 리소스를 테스트할 수 있습니다. 다음 명령으로 서버를 시작하세요:

uv run mcp dev mcp_server.py

그런 다음 브라우저에서 inspector에 연결합니다. 두 개의 섹션이 표시됩니다:

  • Resources - 직접/정적 리소스 목록을 표시합니다
  • Resource Templates - 템플릿 리소스를 표시합니다

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

리소스를 클릭하여 테스트해 보세요. 템플릿 리소스의 경우 매개변수 값을 입력해야 합니다. inspector는 mime 유형과 직렬화된 데이터를 포함하여 클라이언트가 수신할 정확한 응답 구조를 보여줍니다.

실용적인 사용 사례

리소스는 채팅 애플리케이션에서 문서 멘션과 같은 기능을 구현하는 데 이상적입니다. 예를 들어 사용자가 문서를 멘션하기 위해 "@"를 입력하면 다음과 같이 할 수 있습니다:

  1. 직접 리소스를 사용하여 자동완성을 위한 사용 가능한 전체 문서 목록을 가져옵니다
  2. 멘션된 특정 문서의 내용을 가져오기 위해 템플릿 리소스를 사용합니다

이 접근 방식을 사용하면 AI가 도구를 사용하여 정보를 가져올 필요 없이 프롬프트에 문서 콘텐츠를 선제적으로 삽입할 수 있습니다.