콘텐츠로 이동
@aws/nx-plugin
Blog

Python MCP 서버

대형 언어 모델(LLM)에 컨텍스트를 제공하기 위한 Python 모델 컨텍스트 프로토콜(MCP) 서버를 생성하고 선택적으로 Amazon Bedrock AgentCore에 배포합니다.

MCP란?

섹션 제목: “MCP란?”

모델 컨텍스트 프로토콜(MCP)은 AI 어시스턴트가 외부 도구 및 리소스와 상호 작용할 수 있도록 하는 개방형 표준입니다. LLM이 다음을 수행할 수 있는 일관된 방법을 제공합니다:

  • 작업 수행 또는 정보 검색을 위한 도구(함수) 실행
  • 컨텍스트 또는 데이터를 제공하는 리소스 접근

사용 방법

섹션 제목: “사용 방법”

MCP 서버 생성

섹션 제목: “MCP 서버 생성”

Python MCP 서버를 두 가지 방법으로 생성할 수 있습니다:

  1. 설치 Nx Console VSCode Plugin 아직 설치하지 않았다면
  2. VSCode에서 Nx 콘솔 열기
  3. 클릭 Generate (UI) "Common Nx Commands" 섹션에서
  4. 검색 @aws/nx-plugin - py#mcp-server
  5. 필수 매개변수 입력
    • 클릭 Generate

    옵션

    섹션 제목: “옵션”
    매개변수 타입 기본값 설명
    project 필수 string - MCP 서버를 추가할 프로젝트
    computeType string BedrockAgentCoreRuntime MCP 서버를 호스팅할 컴퓨트 유형입니다. 호스팅하지 않으려면 None을 선택하세요.
    name string - MCP 서버의 이름 (기본값: mcp-server)
    auth string IAM MCP 서버 인증에 사용되는 방법입니다. IAM(기본값) 또는 Cognito 중에서 선택하세요.
    iacProvider string Inherit 선호하는 IaC 프로바이더입니다. 기본적으로 초기 선택에서 상속됩니다.

    생성기 출력

    섹션 제목: “생성기 출력”

    생성기는 기존 Python 프로젝트에 다음 파일들을 추가합니다:

    • 디렉터리your-project/
      • 디렉터리your_module/
        • 디렉터리mcp_server/ (사용자 지정 이름 지정 시 변경)
          • __init__.py Python 패키지 초기화
          • server.py 샘플 도구 및 리소스가 포함된 메인 서버 정의
          • stdio.py 단순 로컬 MCP 서버에 유용한 STDIO 전송 진입점
          • http.py MCP 서버 호스팅에 유용한 스트리밍 가능 HTTP 전송 진입점
          • Dockerfile MCP 서버 호스팅용 진입점 (computeType이 None으로 설정된 경우 제외)
      • pyproject.toml MCP 종속성으로 업데이트
      • project.json MCP 서버 실행 대상으로 업데이트

    인프라

    섹션 제목: “인프라”

    이 생성기는 선택한 iacProvider 기반으로 인프라를 코드 형태로 제공하므로, packages/common 디렉터리에 관련 CDK 구축 요소 또는 Terraform 모듈을 포함하는 프로젝트를 생성합니다.

    공통 인프라스트럭처 코드 프로젝트의 구조는 다음과 같습니다:

    • 디렉터리packages/common/constructs
      • 디렉터리src
        • 디렉터리app/ 특정 프로젝트/생성기에 종속적인 인프라를 위한 구축 요소
          • …
        • 디렉터리core/ app 내 구축 요소에서 재사용되는 일반적 구축 요소
          • …
        • index.ts app의 구축 요소를 익스포트하는 진입점
      • project.json 프로젝트 빌드 대상 및 구성

    MCP 서버를 배포하기 위해 다음 파일들이 생성됩니다:

    • 디렉터리packages/common/constructs/src
      • 디렉터리app
        • 디렉터리mcp-servers
          • 디렉터리<project-name>
            • <project-name>.ts MCP 서버 배포를 위한 CDK construct
            • Dockerfile CDK construct에서 사용되는 Passthrough docker 파일

    MCP 서버 작업

    섹션 제목: “MCP 서버 작업”

    도구 추가

    섹션 제목: “도구 추가”

    도구는 AI 어시스턴트가 호출할 수 있는 동작 수행 함수입니다. Python MCP 서버는 MCP Python SDK (FastMCP) 라이브러리를 사용하며, 데코레이터 기반 도구 정의 방식을 제공합니다.

    server.py 파일에 새 도구를 추가할 수 있습니다:

    @mcp.tool(description="도구 설명")
    def your_tool_name(param1: str, param2: int) -> str:
        """타입 힌트가 포함된 도구 구현"""
        # 도구 로직 작성
        return f"결과: {param1} with {param2}"

    FastMCP 라이브러리는 다음을 자동 처리합니다:

    • 함수 타입 힌트 기반 타입 검증
    • MCP 프로토콜용 JSON 스키마 생성
    • 오류 처리 및 응답 포맷팅

    리소스 추가

    섹션 제목: “리소스 추가”

    리소스는 AI 어시스턴트에 컨텍스트를 제공합니다. @mcp.resource 데코레이터로 리소스 추가:

    @mcp.resource("example://static-resource", description="정적 리소스 예시")
    def static_resource() -> str:
        """정적 콘텐츠 반환"""
        return "AI에 컨텍스트를 제공하는 정적 콘텐츠"
    

    @mcp.resource("dynamic://resource/{item_id}", description="동적 리소스 예시")
    def dynamic_resource(item_id: str) -> str:
        """파라미터 기반 동적 콘텐츠 반환"""
        # item_id 기반 데이터 조회
        data = fetch_data_for_item(item_id)
        return f"{item_id}에 대한 동적 콘텐츠: {data}"

    AI 어시스턴트와 연동 설정

    섹션 제목: “AI 어시스턴트와 연동 설정”

    설정 파일

    섹션 제목: “설정 파일”

    MCP를 지원하는 대부분의 AI 어시스턴트는 유사한 설정 방식을 사용합니다. MCP 서버 세부 정보를 포함한 설정 파일을 생성하거나 업데이트해야 합니다:

    {
      "mcpServers": {
        "your-mcp-server": {
          "command": "uv",
          "args": [
            "run",
            "python",
            "-m",
            "my_module.mcp_server.stdio"
          ],
          "env": {
            "VIRTUAL_ENV": "/path/to/your/project/.venv"
          }
        }
      }
    }

    어시스턴트별 설정

    섹션 제목: “어시스턴트별 설정”

    특정 AI 어시스턴트와 MCP를 연동하려면 다음 문서를 참조하세요:

    MCP 서버 실행

    섹션 제목: “MCP 서버 실행”

    인스펙터

    섹션 제목: “인스펙터”

    생성기는 <your-server-name>-inspect 대상을 구성하며, 이는 STDIO 전송을 사용해 MCP 서버에 연결하기 위한 MCP 인스펙터를 시작합니다.

    Terminal window
    pnpm nx your-server-name-inspect your-project

    이 명령은 http://localhost:6274에서 인스펙터를 시작합니다. “Connect” 버튼을 클릭하여 시작하세요.

    STDIO

    섹션 제목: “STDIO”

    MCP 서버를 테스트하고 사용하는 가장 쉬운 방법은 인스펙터 사용이거나 AI 어시스턴트와 연동하는 것입니다.

    STDIO 전송으로 직접 실행하려면 <your-server-name>-serve-stdio 대상을 사용하세요.

    Terminal window
    pnpm nx your-server-name-serve-stdio your-project

    이 명령은 uv run을 사용해 STDIO 전송으로 MCP 서버를 실행합니다.

    스트리밍 가능 HTTP

    섹션 제목: “스트리밍 가능 HTTP”

    스트리밍 가능 HTTP 전송으로 로컬에서 실행하려면 <your-server-name>-serve 대상을 사용하세요.

    Terminal window
    pnpm nx your-server-name-serve your-project

    이 명령은 uv run uvicorn --reload를 사용해 HTTP 전송으로 MCP 서버를 실행하며(일반적으로 8000 포트), 파일 변경 시 자동으로 재시작됩니다.

    Bedrock AgentCore 런타임에 MCP 서버 배포

    섹션 제목: “Bedrock AgentCore 런타임에 MCP 서버 배포”

    인프라스트럭처 코드

    섹션 제목: “인프라스트럭처 코드”

    computeType으로 BedrockAgentCoreRuntime을 선택한 경우 관련 CDK 또는 Terraform 인프라스트럭처가 생성되며, 이를 사용하여 MCP 서버를 Amazon Bedrock AgentCore Runtime에 배포할 수 있습니다.

    생성기 실행 시 선택한 name을 기반으로 MCP 서버용 CDK 구성 요소가 생성되며, 기본값은 <ProjectName>McpServer입니다.

    이 CDK 구성 요소를 CDK 애플리케이션에서 사용할 수 있습니다:

    import { MyProjectMcpServer } from ':my-scope/common-constructs';
    

    export class ExampleStack extends Stack {
      constructor(scope: Construct, id: string) {
        // 스택에 MCP 서버 추가
        new MyProjectMcpServer(this, 'MyProjectMcpServer');
      }
    }

    인증

    섹션 제목: “인증”

    생성기는 MCP 서버의 인증을 구성하기 위한 auth 옵션을 제공합니다. MCP 서버 생성 시 IAM(기본값) 또는 Cognito 인증 중에서 선택할 수 있습니다.

    IAM

    섹션 제목: “IAM”

    기본적으로 MCP 서버는 IAM 인증을 사용하여 보호됩니다. 인수 없이 배포하면 됩니다:

    import { MyProjectMcpServer } from ':my-scope/common-constructs';
    

    export class ExampleStack extends Stack {
      constructor(scope: Construct, id: string) {
        new MyProjectMcpServer(this, 'MyProjectMcpServer');
      }
    }

    grantInvokeAccess 메서드를 사용하여 Bedrock AgentCore Runtime에서 MCP 서버 호출 권한을 부여할 수 있습니다. 예를 들어 py#strands-agent 생성기로 생성된 에이전트가 MCP 서버를 호출하도록 허용할 수 있습니다:

    import { MyProjectAgent, MyProjectMcpServer } from ':my-scope/common-constructs';
    

    export class ExampleStack extends Stack {
      constructor(scope: Construct, id: string) {
        const agent = new MyProjectAgent(this, 'MyProjectAgent');
        const mcpServer = new MyProjectMcpServer(this, 'MyProjectMcpServer');
    

        mcpServer.grantInvokeAccess(agent);
      }
    }

    Cognito 인증

    섹션 제목: “Cognito 인증”

    Cognito 인증을 선택하면 생성기가 MCP 서버가 Cognito를 사용하여 인증하도록 구성합니다.

    생성된 구성 요소는 Cognito 인증을 구성하는 identity prop을 받습니다:

    import { MyProjectMcpServer, UserIdentity } from ':my-scope/common-constructs';
    

    export class ExampleStack extends Stack {
      constructor(scope: Construct, id: string) {
        const identity = new UserIdentity(this, 'Identity');
    

        new MyProjectMcpServer(this, 'MyProjectMcpServer', {
          identity,
        });
      }
    }

    UserIdentity 구성 요소는 ts#react-website#auth 생성기를 사용하여 생성하거나, 직접 CDK UserPool 및 UserPoolClient를 생성할 수 있습니다.

    번들 및 Docker 대상

    섹션 제목: “번들 및 Docker 대상”

    Bedrock AgentCore 런타임용 MCP 서버 빌드를 위해 프로젝트에 bundle 대상이 추가됩니다. 이 대상은:

    • uv export를 사용해 Python 종속성을 requirements.txt 파일로 내보냄
    • 대상 플랫폼(aarch64-manylinux_2_28)용 종속성을 uv pip install로 설치

    또한 MCP 서버 전용 docker 대상이 추가되어 Dockerfile과 번들된 아티팩트를 docker 컨텍스트 디렉토리로 복사합니다. 이를 통해 Dockerfile이 빌드 출력과 동일 위치에 배치되어 CDK가 AgentRuntimeArtifact.fromAsset을 사용해 Docker 이미지를 직접 빌드할 수 있습니다.

    관측성

    섹션 제목: “관측성”

    MCP 서버는 Dockerfile에 자동 계측을 구성하여 AWS Distro for Open Telemetry(ADOT)를 사용해 관측 가능성을 자동으로 구성합니다.

    트레이스는 CloudWatch AWS 콘솔에서 메뉴의 “GenAI Observability”를 선택해 확인할 수 있습니다. 트레이스 데이터가 표시되려면 트랜잭션 검색을 활성화해야 합니다.

    자세한 내용은 AgentCore 관측 가능성 문서를 참조하세요.