리소스 정의하기

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

예제를 통해 리소스 이해하기

사용자가 @document_name을 입력하여 파일을 참조할 수 있는 문서 멘션 기능을 만들고자 한다고 가정해 보겠습니다. 이를 위해서는 두 가지 작업이 필요합니다:

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

사용자가 문서를 멘션하면, 시스템은 Claude에게 전송되는 프롬프트에 해당 문서의 내용을 자동으로 삽입하여 Claude가 정보를 가져오기 위해 도구를 사용할 필요를 없애줍니다.

리소스 작동 방식

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

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

리소스의 유형

리소스에는 두 가지 유형이 있습니다:

직접 리소스(Direct Resources)

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

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

템플릿 리소스(Templated Resources)

템플릿 리소스는 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 Inspector를 사용하여 리소스를 테스트할 수 있습니다. 다음 명령으로 서버를 시작하세요:

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

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

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

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