Python MCP Server

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

MCP란 무엇인가요?

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

작업을 수행하거나 정보를 검색하는 도구(함수) 실행
컨텍스트 또는 데이터를 제공하는 리소스 액세스

사용법

MCP Server 생성

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

CLI
VSCode

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

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

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

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

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

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

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

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

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

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

옵션

매개변수	타입	기본값	설명
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/ (or custom name if specified)
    __init__.py Python package initialization
    server.py Main server definition with sample tools and resources
    stdio.py Entry point for STDIO transport, useful for simple local MCP servers
    http.py Entry point for Streamable HTTP transport, useful for hosting your MCP server
    Dockerfile Entry point for hosting your MCP server (excluded when infra is set to None)
- pyproject.toml Updated with MCP dependencies
- project.json Updated with MCP server serve targets

인프라

이 생성기는 선택한 iac를 기반으로 코드형 인프라를 제공하므로, 관련 CDK constructs 또는 Terraform 모듈을 포함하는 packages/common에 프로젝트를 생성합니다.

공통 코드형 인프라 프로젝트는 다음과 같이 구성됩니다:

CDK
Terraform

디렉터리packages/common/constructs
- 디렉터리src
  - 디렉터리app/ 프로젝트/생성기에 특정한 인프라를 위한 Constructs
    …
  - 디렉터리core/ app의 constructs에서 재사용되는 일반 constructs
    …
  - index.ts app에서 constructs를 내보내는 진입점
- project.json 프로젝트 빌드 타겟 및 구성

디렉터리packages/common/terraform
- 디렉터리src
  - 디렉터리app/ 프로젝트/생성기에 특정한 인프라를 위한 Terraform 모듈
    …
  - 디렉터리core/ app의 모듈에서 재사용되는 일반 모듈
    …
- project.json 프로젝트 빌드 타겟 및 구성

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

CDK
Terraform

디렉터리packages/common/constructs/src
- 디렉터리app
  - 디렉터리mcp-servers
    디렉터리<mcp-server-name>
    <mcp-server-name>.ts CDK construct for deploying your MCP Server

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

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

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

MCP Server 작업하기

도구 추가

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

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

@mcp.tool(description="Your tool description")
def your_tool_name(param1: str, param2: int) -> str:
    """Tool implementation with type hints"""
    # Your tool logic here
    return f"Result: {param1} with {param2}"

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

함수의 타입 힌트를 기반으로 한 타입 검증
MCP 프로토콜을 위한 JSON 스키마 생성
오류 처리 및 응답 포맷팅

리소스 추가

리소스는 AI 어시스턴트에 컨텍스트를 제공합니다. @mcp.resource 데코레이터를 사용하여 리소스를 추가할 수 있습니다:

@mcp.resource("example://static-resource", description="Static resource example")
def static_resource() -> str:
    """Return static content"""
    return "This is static content that provides context to the AI"

@mcp.resource("dynamic://resource/{item_id}", description="Dynamic resource example")
def dynamic_resource(item_id: str) -> str:
    """Return dynamic content based on parameters"""
    # Fetch data based on item_id
    data = fetch_data_for_item(item_id)
    return f"Dynamic content for {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"
      }
    }
  }
}

어시스턴트별 구성

특정 AI 어시스턴트에서 MCP를 구성하는 방법은 다음 문서를 참조하세요:

MCP Server 실행

로컬 개발

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

pnpm nx dev your-project

yarn nx dev your-project

npx nx dev your-project

bunx nx dev your-project

프로젝트에 여러 컴포넌트(MCP 서버, 에이전트 등)를 추가한 경우, 이는 모두 시작합니다. 이 MCP 서버만 실행하려면 <your-server-name>-dev 타겟을 대상으로 지정하세요:

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

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

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

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

Inspector

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

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

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

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

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

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

STDIO

MCP 서버를 테스트하고 사용하는 가장 쉬운 방법은 인스펙터를 사용하거나 AI 어시스턴트와 구성하는 것입니다(위 참조).

그러나 <your-server-name>-serve-stdio 타겟을 사용하여 STDIO 전송으로 서버를 직접 실행할 수 있습니다.

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

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

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

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

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

Streamable HTTP

Streamable HTTP 전송을 사용하여 MCP 서버를 로컬에서 실행하려면 <your-server-name>-serve 타겟을 사용할 수 있습니다.

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

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

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

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

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

Bedrock AgentCore Runtime에 MCP Server 배포

Infrastructure as Code

infra에 대해 agentcore를 선택한 경우, MCP 서버를 Amazon Bedrock AgentCore Runtime에 배포하는 데 사용할 수 있는 관련 CDK 또는 Terraform 인프라가 생성됩니다.

CDK
Terraform

MCP 서버에 대한 CDK 구성이 생성되며, 제너레이터를 실행할 때 선택한 name을 기반으로 이름이 지정되거나 기본적으로 <ProjectName>McpServer로 지정됩니다.

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

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

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // Add the MCP server to your stack
    new MyProjectMcpServer(this, 'MyProjectMcpServer');
  }
}

제너레이터를 실행할 때 선택한 name을 기반으로 이름이 지정되거나 기본적으로 <ProjectName>-mcp-server로 지정된 Terraform 모듈이 생성됩니다.

공유 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
}

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
Terraform

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

# MCP Server
module "my_project_mcp_server" {
  # Relative path to the generated module in the common/terraform project
  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 인증을 선택하면 제너레이터가 인증에 Cognito를 사용하도록 MCP 서버를 구성합니다.

CDK
Terraform

생성된 구성은 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를 생성할 수 있습니다.

생성된 모듈은 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]
}

Bundle 및 Docker 타겟

Bedrock AgentCore Runtime을 위해 MCP 서버를 빌드하기 위해 프로젝트에 bundle 타겟이 추가되며, 이는 다음을 수행합니다:

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

MCP 서버에 특정한 docker 타겟도 추가되며, 이는 Dockerfile과 번들된 아티팩트를 docker 컨텍스트 디렉터리에 복사합니다. 이는 Dockerfile을 빌드 출력과 함께 배치하여 CDK가 AgentRuntimeArtifact.fromAsset을 사용하여 Docker 이미지를 직접 빌드할 수 있도록 합니다.

이미지 스캔

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

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

스캔은 이미지 빌드와 동일한 컨테이너 엔진(docker 또는 finch)을 사용하므로 추가 도구가 필요하지 않습니다. 스캔은 이미지가 변경될 때만 다시 실행되므로 변경되지 않은 이미지는 다시 스캔되지 않습니다. 제공되는 trivy 루트 스크립트는 워크스페이스의 모든 이미지를 스캔합니다:

pnpm trivy

yarn trivy

npm run trivy

bun trivy

Trivy 결과 억제

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

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

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

결과 필터링에 대한 자세한 내용은 Trivy 필터링 문서를 참조하세요.

관찰 가능성

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

CloudWatch AWS Console에서 메뉴의 “GenAI Observability”를 선택하여 추적을 찾을 수 있습니다. 추적이 채워지려면 Transaction Search를 활성화해야 합니다.

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

연결

connection 생성기를 사용하여 이 프로젝트를 워크스페이스의 다른 프로젝트와 통합하세요. 다음 연결은 이 프로젝트와 관련됩니다:

TypeScript Agent to MCPConnect a TypeScript Agent to an MCP server

Python Agent to MCPConnect a Python Agent to an MCP server

Python MCP Server to Python DynamoDBConnect a Python MCP Server to a DynamoDB table

AgentCore Gateway to MCP ServerAggregate an MCP server behind an AgentCore Gateway