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	-	The project to add an MCP server to
computeType	string	BedrockAgentCoreRuntime	The type of compute to host your MCP server. Select None for no hosting.
name	string	-	The name of your MCP server (default: mcp-server)
iacProvider	string	CDK	The preferred IaC provider

생성기 출력

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

• 디렉터리your-project/

  • 디렉터리your_module/

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

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

인프라

참고

computeType을 None으로 선택한 경우 생성기는 인프라 코드를 생성하지 않습니다.

이 생성기는 선택한 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 파일
  • 디렉터리core

    • 디렉터리agent-core

      • runtime.ts Bedrock AgentCore Runtime에 배포하기 위한 일반적인 CDK construct

Terraform

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

  • 디렉터리app

    • 디렉터리mcp-servers

      • 디렉터리<project-name>

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

    • 디렉터리agent-core

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

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를 연동하려면 다음 문서를 참조하세요:

• Amazon Q Developer
• Cline
• Cursor
• Claude Code
• Roo Code

팁

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

MCP 서버 실행

인스펙터

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

pnpm

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

yarn

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

npm

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

bun

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

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

STDIO

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

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

pnpm

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

yarn

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

npm

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

bun

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

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

스트리밍 가능 HTTP

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

pnpm

pnpm nx run your-project:your-server-name-serve-http

yarn

yarn nx run your-project:your-server-name-serve-http

npm

npx nx run your-project:your-server-name-serve-http

bun

bunx nx run your-project:your-server-name-serve-http

이 명령은 일반적으로 8000 포트에서 HTTP 전송으로 MCP 서버를 실행합니다.

Bedrock AgentCore 런타임에 MCP 서버 배포

인프라스트럭처 코드

생성기 실행 시 computeType으로 BedrockAgentCoreRuntime을 선택한 경우, Amazon Bedrock AgentCore Runtime에 MCP 서버를 배포하는 데 사용할 수 있는 관련 CDK 또는 Terraform 인프라가 생성됩니다.

CDK

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

Terraform

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

이 Terraform 모듈을 Terraform 프로젝트에서 사용할 수 있습니다:

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

주의

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

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

인증

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

grantInvoke 메서드를 사용하여 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.agentCoreRuntime.grantInvoke(agent.agentCoreRuntime);
  }
}

Terraform

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

에이전트 호출 권한을 부여하려면 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 JWT 인증

다음은 에이전트에 Cognito 인증을 구성하는 방법을 보여줍니다.

CDK

JWT 인증을 구성하려면 MCP 서버 구성요소에 authorizerConfiguration 속성을 전달할 수 있습니다. 다음은 Cognito 사용자 풀과 클라이언트를 구성하여 MCP 서버를 보호하는 예시입니다:

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

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const userPool = new UserPool(this, 'UserPool');
    const client = userPool.addClient('Client', {
      authFlows: {
        userPassword: true,
      },
    });

    new MyProjectMcpServer(this, 'MyProjectMcpServer', {
      authorizerConfiguration: {
        customJWTAuthorizer: {
          discoveryUrl: `https://cognito-idp.${Stack.of(userPool).region}.amazonaws.com/${userPool.userPoolId}/.well-known/openid-configuration`,
          allowedClients: [client.userPoolClientId],
        },
      },
    });
  }
}

Terraform

JWT 인증을 구성하려면 MCP 서버 모듈의 customJWTAuthorizer 변수를 다음과 같이 수정할 수 있습니다:

packages/common/terraform/src/app/mcp-servers/my-project-mcp-server/my-project-mcp-server.tf

data "aws_region" "current" {}

locals {
  aws_region = data.aws_region.current.name

  # 사용자 풀 및 클라이언트 ID로 교체하거나 변수로 노출
  user_pool_id = "xxx"
  user_pool_client_ids = ["yyy"]
}

module "agent_core_runtime" {
  source = "../../../core/agent-core"
  agent_runtime_name = "MyProjectMcpServer"
  docker_image_tag = "my-scope-my-project-agent:latest"
  server_protocol = "MCP"
  customJWTAuthorizer = {
    discoveryUrl = "https://cognito-idp.${local.aws_region}.amazonaws.com/${local.user_pool_id}/.well-known/openid-configuration",
    allowedClients = local.user_pool_client_ids
  }
  env = var.env
  additional_iam_policy_statements = var.additional_iam_policy_statements
  tags = var.tags
}

번들 및 Docker 대상

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

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

또한 MCP 서버 전용 docker 대상이 추가되어:

• Dockerfile에서 포트 8000으로 MCP 서버를 실행하는 도커 이미지 빌드 (MCP 프로토콜 계약 준수)

팁

도커 이미지는 태그(예: my-scope-my-project-mcp-server:latest)로 빌드되며, 이는 CDK나 Terraform 인프라에서 참조되어 MCP 서버 프로젝트와 동일 위치에 Dockerfile을 유지할 수 있게 합니다.

관측성

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

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

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