Python MCP 서버

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

MCP란?

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

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

사용 방법

MCP 서버 생성

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

VSCode

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:py#mcp-server

yarn

yarn nx g @aws/nx-plugin:py#mcp-server

npm

npx nx g @aws/nx-plugin:py#mcp-server

bun

bunx nx g @aws/nx-plugin:py#mcp-server

어떤 파일이 변경될지 확인하기 위해 드라이 런을 수행할 수도 있습니다

pnpm

pnpm nx g @aws/nx-plugin:py#mcp-server --dry-run

yarn

yarn nx g @aws/nx-plugin:py#mcp-server --dry-run

npm

npx nx g @aws/nx-plugin:py#mcp-server --dry-run

bun

bunx nx g @aws/nx-plugin:py#mcp-server --dry-run

프로젝트 사전 요건

먼저 MCP 서버를 추가할 프로젝트를 생성하기 위해 py#project 생성기를 사용하세요.

옵션

매개변수	타입	기본값	설명
project 필수	string	-	MCP 서버를 추가할 프로젝트
name	string	-	MCP 서버의 이름 (기본값: mcp-server)
auth	iam | cognito	iam	MCP 서버 인증에 사용되는 방법입니다. infra가 설정된 경우에만 적용됩니다 (infra가 none일 때는 무시됨).
iac	inherit | cdk | terraform	inherit	선호하는 IaC 프로바이더입니다. 기본적으로 초기 선택에서 상속됩니다.
infra	agentcore | none	agentcore	MCP 서버를 호스팅할 인프라 유형입니다. 호스팅이 필요 없는 경우 none을 선택하세요.
preferInstallDependencies	boolean	true	생성기 실행 후 의존성 설치를 선호할지 여부입니다. 여러 생성기를 일괄 처리할 때 설치를 연기하려면 false로 설정하세요 (후속 생성기가 Nx 프로젝트 그래프를 계산할 수 있도록 필요한 경우 설치는 여전히 실행됩니다); 마지막에 한 번 설치합니다.

생성기 출력

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

• 디렉터리your-project/

  • 디렉터리your_module/

    • 디렉터리mcp_server/ (사용자 지정 이름 지정 시 변경)

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

인프라

infra = agentcore

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

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

CDK

• 디렉터리packages/common/constructs

  • 디렉터리src

    • 디렉터리app/ 특정 프로젝트/생성기에 종속적인 인프라를 위한 구축 요소

      • …
    • 디렉터리core/ app 내 구축 요소에서 재사용되는 일반적 구축 요소

      • …
    • index.ts app의 구축 요소를 익스포트하는 진입점
  • project.json 프로젝트 빌드 대상 및 구성

생성된 프로젝트

이 프로젝트는 ts#project 생성기를 사용하여 생성되었으므로 동일한 빌드 대상이 구성됩니다.

Terraform

• 디렉터리packages/common/terraform

  • 디렉터리src

    • 디렉터리app/ 특정 프로젝트/생성기 전용 Terraform 모듈

      • …
    • 디렉터리core/ app 내 모듈에서 재사용되는 일반적 모듈

      • …
  • project.json 프로젝트 빌드 대상 및 구성

생성된 프로젝트

이 프로젝트는 terraform#project 생성기를 사용하여 생성되었으므로 동일한 빌드 대상이 구성됩니다.

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

CDK

• 디렉터리packages/common/constructs/src

  • 디렉터리app

    • 디렉터리mcp-servers

      • 디렉터리<project-name>

        • <project-name>.ts MCP 서버 배포를 위한 CDK construct
        • Dockerfile CDK construct에서 사용되는 Passthrough docker 파일

Terraform

• 디렉터리packages/common/terraform/src

  • 디렉터리app

    • 디렉터리mcp-servers

      • 디렉터리<project-name>

        • <project-name>.tf MCP 서버 배포를 위한 모듈
  • 디렉터리core

    • 디렉터리agent-core

      • runtime.tf Bedrock AgentCore Runtime에 배포하기 위한 일반적인 모듈

infra = none

infra을 None으로 선택한 경우 CDK 구성 또는 Terraform 모듈이 생성되지 않습니다 — MCP 서버는 로컬 STDIO / HTTP 사용만을 위해 구성됩니다. 호스팅되는 엔드포인트가 없어 인증할 필요가 없으므로 이 모드에서는 auth 옵션이 무시됩니다.

아키텍처

Bedrock AgentCore Runtime

Bedrock AgentCore Runtime에 배포되면, MCP 서버는 컨테이너 이미지로 빌드되어 Amazon ECR에 푸시되고 AgentCore Runtime에서 실행됩니다. AI 어시스턴트는 AgentCore Runtime 데이터 플레인 엔드포인트를 호출하며, 이는 streamable HTTP transport를 통해 tools/* 및 resources/* 호출을 서버로 전달합니다.

None (local only)

infra: None을 사용하면 AWS 인프라가 생성되지 않습니다. MCP 서버는 로컬 STDIO 및 HTTP 전송만을 위해 구성되며, 동일한 머신에서 실행되는 AI 어시스턴트에 의해 사용됩니다.

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 어시스턴트와 연동 설정

설정 파일

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"
      }
    }
  }
}

경로 해석

서버에 연결할 때 ENOENT uv와 같은 오류가 발생한다면, 터미널에서 which uv를 실행하여 얻을 수 있는 uv의 전체 경로를 지정해야 할 수 있습니다.

어시스턴트별 설정

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

• Kiro
• Kiro CLI
• Claude Code
• Cursor
• Codex
• Cline
• Roo Code

워크스페이스 구성

Amazon Q Developer와 같은 일부 AI 어시스턴트는 워크스페이스 수준의 MCP 서버 구성을 허용하며, 이는 특정 프로젝트에 관련된 MCP 서버를 정의할 때 특히 유용합니다.

MCP 서버 실행

로컬 개발

MCP 서버(및 로컬 데이터베이스와 같이 연결된 모든 것)를 로컬에서 실행하려면 프로젝트의 dev 대상을 사용하세요:

pnpm

pnpm nx dev your-project

yarn

yarn nx dev your-project

npm

npx nx dev your-project

bun

bunx nx dev your-project

프로젝트에 여러 컴포넌트(MCP 서버, 에이전트 등)를 추가한 경우 이 명령은 모든 컴포넌트를 시작합니다. 이 MCP 서버만 실행하려면 <your-server-name>-dev 대상을 사용하세요:

pnpm

pnpm nx your-server-name-dev your-project

yarn

yarn nx your-server-name-dev your-project

npm

npx nx your-server-name-dev your-project

bun

bunx nx your-server-name-dev your-project

인스펙터

생성기는 <your-server-name>-inspect 대상을 구성하며, 이는 MCP 서버를 로컬에서 시작하고(<your-server-name>-dev 대상을 통해 로컬 데이터베이스와 같은 연결된 종속성 포함) 스트리밍 가능 HTTP 전송을 통해 연결하도록 사전 구성된 MCP 인스펙터를 실행합니다.

pnpm

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

yarn

yarn nx your-server-name-inspect your-project

npm

npx nx your-server-name-inspect your-project

bun

bunx nx your-server-name-inspect your-project

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

팁

대신 STDIO 전송을 사용하여 서버를 검사하려면 <your-server-name>-inspect-stdio 대상을 사용하세요. 이는 서버의 STDIO 인스턴스에 대해 인스펙터를 실행합니다.

STDIO

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

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

pnpm

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

yarn

yarn nx your-server-name-serve-stdio your-project

npm

npx nx your-server-name-serve-stdio your-project

bun

bunx nx your-server-name-serve-stdio your-project

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

스트리밍 가능 HTTP

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

pnpm

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

yarn

yarn nx your-server-name-serve your-project

npm

npx nx your-server-name-serve your-project

bun

bunx nx your-server-name-serve your-project

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

infra = agentcore

Bedrock AgentCore 런타임에 MCP 서버 배포

인프라스트럭처 코드

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

CDK

생성기 실행 시 선택한 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');
  }
}

CDK 컨스트럭트

이 구성 요소는 aws-cdk-lib/aws-bedrockagentcore 모듈을 사용합니다.

Terraform

생성기 실행 시 선택한 name을 기반으로 Terraform 모듈이 생성되며, 기본값은 <ProjectName>-mcp-server입니다.

공유 runtime_config_appconfig 모듈의 출력을 MCP 서버 모듈에 전달합니다:

module "my_project_mcp_server" {
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

Docker 필요

MCP 서버 빌드 및 배포를 위해 Docker가 필요합니다. 다음 오류를 방지하려면 Docker가 설치되어 실행 중인지 확인하세요:

ERROR: Cannot connect to the Docker daemon at unix://path/to/docker.sock.

인증

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

IAM

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

CDK

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#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);
  }
}

Terraform

# MCP 서버
module "my_project_mcp_server" {
  # common/terraform 프로젝트 내 생성된 모듈의 상대 경로
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

MCP 서버 호출 권한을 부여하려면 module.my_project_mcp_server.agent_core_runtime_arn 출력을 참조하는 다음과 같은 정책을 추가해야 합니다:

{
  Effect = "Allow"
  Action = [
    "bedrock-agentcore:InvokeAgentRuntime"
  ]
  Resource = [
    module.my_project_mcp_server.agent_core_runtime_arn,
    "${module.my_project_mcp_server.agent_core_runtime_arn}/*"
  ]
}

Cognito 인증

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

CDK

생성된 구성 요소는 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#website#auth 생성기를 사용하여 생성하거나, 직접 CDK UserPool 및 UserPoolClient를 생성할 수 있습니다.

Terraform

생성된 모듈은 Cognito 인증을 위한 user_pool_id 및 user_pool_client_ids 변수를 받습니다:

module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

module "my_project_mcp_server" {
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn

  user_pool_id         = module.user_identity.user_pool_id
  user_pool_client_ids = [module.user_identity.user_pool_client_id]
}

사용자 정의 OIDC 프로바이더

Cognito가 아닌 OIDC 공급자를 사용한 사용자 정의 JWT 인증이 필요한 경우 MCP 서버용으로 생성된 CDK 구성 요소 또는 Terraform 모듈을 직접 수정할 수 있습니다. 연결 생성기는 IAM 또는 Cognito 인증만 지원한다는 점에 유의하세요.

보안 모범 사례

MCP 서버의 비즈니스 로직을 구현할 때 Bedrock AgentCore Runtime 보안 모범 사례를 검토하세요.

번들 및 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 이미지를 직접 빌드할 수 있습니다.

이미지 스캔

이 프로젝트를 위해 빌드된 Docker 이미지는 ECR 호스팅 Trivy 이미지에서 실행되는 Trivy를 사용하여 빌드의 일부로 취약점을 스캔합니다.

trivy 타겟이 프로젝트에 추가되어 빌드된 이미지를 스캔하고, HIGH 또는 CRITICAL 심각도 취약점이 발견되면 빌드를 실패시킵니다. 생성된 Dockerfile은 생성 시점에 이러한 심각도의 알려진 수정 가능한 취약점이 없는 베이스 이미지를 사용하며, 이를 유지하기 위해 번들된 도구(예: npm)를 업그레이드합니다.

스캔은 이미지 빌드와 동일한 컨테이너 엔진(docker 또는 finch)을 사용하므로 추가 도구가 필요하지 않습니다. 스캔은 이미지가 변경될 때만 다시 실행되므로 변경되지 않은 이미지는 다시 스캔되지 않습니다.

수정 불가능한 취약점은 무시됩니다

스캔은 --ignore-unfixed로 실행되므로 사용 가능한 수정 사항이 없는 취약점은 빌드를 실패시키지 않습니다. 이는 Dockerfile에서 도구를 업그레이드하여 조치할 수 없기 때문이며, 빌드의 스캔 출력에 보고되지 않습니다. 새로운 취약점이 공개됨에 따라 스캔 결과가 시간이 지남에 따라 변경될 수 있으므로, 플래그 없이 trivy image <your-image>를 실행하여 주기적으로 이미지를 검토하고, 수정 사항이 게시되면 최신 베이스 이미지로 다시 빌드하거나 (또는 사용 가능한 패치를 적용하기 위해 컨테이너 단계를 추가) 하십시오.

Trivy 발견 사항 억제

특정 취약점을 억제하고 싶은 경우가 있을 수 있습니다. 예를 들어 아직 수정 사항이 없고 위험을 허용 가능한 것으로 평가한 경우입니다.

프로젝트 루트(즉, project.json 옆)의 .trivyignore 파일에 취약점 ID를 한 줄에 하나씩 추가하십시오:

.trivyignore

# node-tar arbitrary file write - not exploitable in our usage
CVE-2024-XXXXX

발견 사항 필터링에 대한 자세한 내용은 Trivy 필터링 문서를 참조하십시오.

관측성

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

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

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

연결

connection 생성기를 사용하여 이 프로젝트를 워크스페이스의 다른 프로젝트와 통합할 수 있습니다. 다음은 이 프로젝트와 관련된 연결입니다:

TypeScript Agent to MCPTypeScript Agent를 MCP 서버에 연결하기

Python Agent to MCPPython Agent를 MCP 서버에 연결하기

Python MCP Server to Python DynamoDBPython MCP Server를 DynamoDB 테이블에 연결하기

AgentCore Gateway to MCP ServerAgentCore Gateway 뒤에 MCP 서버 집계하기