Defining resources

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

예제를 통한 리소스 이해

사용자가 @document_name을 입력하여 파일을 참조할 수 있는 문서 멘션 기능을 구축하고 싶다고 가정해 봅시다. 이를 위해서는 두 가지 작업이 필요합니다:

사용 가능한 모든 문서 목록 가져오기 (자동완성용)
특정 문서의 내용 가져오기 (멘션 시)

사용자가 문서를 멘션하면, 시스템이 자동으로 문서 내용을 Claude에게 보내는 프롬프트에 주입하여 Claude가 도구를 사용하여 정보를 가져올 필요를 없앱니다.

리소스 작동 방식

리소스는 요청-응답 패턴을 따릅니다. 클라이언트가 데이터를 필요로 할 때, 원하는 리소스를 식별하기 위한 URI와 함께 ReadResourceRequest를 보냅니다. MCP 서버는 이 요청을 처리하고 ReadResourceResult로 데이터를 반환합니다.

흐름은 다음과 같습니다: 여러분의 코드가 MCP 클라이언트에 리소스를 요청하고, 클라이언트가 요청을 MCP 서버로 전달합니다. 서버는 URI를 처리하고, 적절한 함수를 실행하며, 결과를 반환합니다.

리소스 유형

두 가지 유형의 리소스가 있습니다:

직접 리소스

직접 리소스는 변경되지 않는 정적 URI를 가집니다. 매개변수가 필요하지 않은 작업에 적합합니다.

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

템플릿 리소스

템플릿 리소스는 URI에 매개변수를 포함합니다. Python SDK는 이러한 매개변수를 자동으로 파싱하여 키워드 인자로 함수에 전달합니다.

@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]

구현 세부 사항

리소스는 문자열, JSON, 바이너리 데이터 등 모든 유형의 데이터를 반환할 수 있습니다. mime_type 매개변수를 사용하여 반환하는 데이터의 종류를 클라이언트에 알려주세요:

"application/json" - 구조화된 데이터
"text/plain" - 일반 텍스트
"application/pdf" - 바이너리 파일

MCP Python SDK는 반환 값을 자동으로 직렬화합니다. 객체를 JSON 문자열로 직접 변환할 필요 없이, 데이터 구조를 반환하면 SDK가 직렬화를 처리합니다.

리소스 테스트하기

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

uv run mcp dev mcp_server.py

그런 다음 브라우저에서 검사기에 연결하세요. 두 섹션이 표시됩니다:

Resources - 직접/정적 리소스 목록
Resource Templates - 템플릿 리소스 목록

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

리소스는 MCP 서버에서 읽기 전용 데이터를 노출하는 깔끔한 방법을 제공하여, 클라이언트가 도구 호출의 복잡함 없이 쉽게 정보를 가져올 수 있게 합니다.

Header Navigation