프로그래밍공부(Programming Study)/AI&ML-Agent AI

Amazon Q Developer MCP 서버 설정 – command와 args 완전 이해

Chann._.y 2025. 9. 18.

728x90

지난 글에서는 MCP 서버 개발에서 헷갈리는 uv, uvx, npm, npx 개념을 정리했습니다.
이번 글에서는 Amazon Q Developer에서 MCP 서버를 연결할 때 꼭 필요한 설정 파일인 mcp.json의 command와 args를 어떻게 작성해야 하는지 구체적으로 알아봅니다.

1. MCP 서버 설정 개요

Amazon Q Developer는 MCP 서버를 실행할 때,

command: 어떤 실행기를 쓸지 (python, uv, uvx, node, npm, npx 등)
args: 그 실행기에 넘길 인자들

을 지정해야 합니다.

즉, 로컬 환경인지 / 배포 환경인지 / Python 기반인지 / Node.js 기반인지에 따라 설정이 달라집니다.

2. Python MCP 서버 설정 패턴

(1) 로컬 개발 – uv run

{
  "mcpServers": {
    "hello-server": {
      "command": "uv",
      "args": ["run", "hello-mcp-server"]
    }
  }
}

(2) 배포 후 실행 – uvx

{
  "mcpServers": {
    "hello-server": {
      "command": "uvx",
      "args": ["hello-mcp-server"]
    }
  }
}

(3) 단순 스크립트 실행

{
  "mcpServers": {
    "hello-server": {
      "command": "python3",
      "args": ["hello_mcp_server.py"]
    }
  }
}

3. Node.js MCP 서버 설정 패턴

(1) npm run

{
  "mcpServers": {
    "hello-server": {
      "command": "npm",
      "args": ["run", "start"]
    }
  }
}

(2) npx 실행

{
  "mcpServers": {
    "hello-server": {
      "command": "npx",
      "args": ["my-mcp-server"]
    }
  }
}

4. 정리 표

환경/언어	command	args 예시	특징
Python (로컬)	`uv`	`["run", "hello-mcp-server"]`	개발 중, .venv 활용
Python (배포)	`uvx`	`["hello-mcp-server"]`	PyPI 배포 후 전역 설치 불필요
Python (스크립트)	`python3`	`["hello_mcp_server.py"]`	단순 실행, 경로 이슈 주의
Node.js (로컬)	`npm`	`["run", "start"]`	package.json script 실행
Node.js (배포)	`npx`	`["my-mcp-server"]`	npm registry에서 실행

5. DevOps 엔지니어를 위한 실무 팁

개발 단계: uv run (Python) / npm run (Node.js)
배포 단계: uvx (PyPI) / npx (npm)
CI/CD: args에 버전 명시 (hello-mcp-server==1.0.0)로 재현성 보장

6. 마무리

command는 실행기, args는 실행 대상
Python 생태계는 uv/uvx, Node.js 생태계는 npm/npx로 대응
개발과 배포, 로컬과 전역 실행을 구분하면 헷갈릴 일이 없습니다.

📌 다음 글 예고
Hello World MCP 서버 – Python & Node.js 구현과 Amazon Q Developer 연결에서는 실제로 Hello World MCP 서버를 Python/Node.js 양쪽으로 구현하고, Amazon Q Developer에 붙여보는 과정을 다룰 예정입니다.