Amazon Q Developer MCP 설정: command·args·절대경로 읽는 법

local MCP server 설정에서 command와 args는 host가 어떤 child process를 어떻게 시작할지를 표현한다. 둘을 shell command 한 줄처럼 취급하면 path, working directory, quoting 문제를 찾기 어렵다.

{
  "command": "uv",
  "args": ["--directory", "/ABSOLUTE/PATH/hello", "run", "server.py"]
}

이 설정은 대략 다음 process invocation에 대응한다.

executable: uv
argv[1]: --directory
argv[2]: /ABSOLUTE/PATH/hello
argv[3]: run
argv[4]: server.py

command는 실행 가능한 program이다

command에는 일반적으로 uv, python3, node, npm 같은 executable 이름이나 그 absolute path가 들어간다. "uv run server.py" 전체를 하나의 command로 넣는 방식은 host가 shell을 자동 해석한다고 보장할 수 없어 피한다.

desktop app이나 CLI에서 보이는 PATH는 interactive shell과 다를 수 있다. terminal에서는 되는데 host에서는 executable을 못 찾는다면 다음을 read-only로 확인한다.

command -v uv
command -v node

필요하면 출력된 absolute path를 command에 쓴다. 개인 home path나 username이 포함된 설정을 공개 글·repository에 그대로 올리지는 않는다.

args는 공백으로 합칠 문자열이 아니다

각 argument는 array 원소 하나다. path에 공백이 있더라도 JSON 원소 안에서는 별도 shell quote를 덧붙이지 않는다.

{
  "command": "node",
  "args": ["/Users/me/My Project/build/index.js"]
}

Amazon Q Developer CLI의 --args option으로 등록할 때 comma가 들어간 argument는 escape 또는 JSON array 형식을 사용하라고 현재 공식 문서가 안내한다. file을 직접 추측해 고치기보다 설치된 version의 qchat mcp help와 공식 CLI 문서를 함께 확인한다.

Python 실행 패턴

목적	command	args 예시	주의점
uv project source 실행	uv	--directory, absolute project path, run, server.py	lockfile과 project environment 사용
plain Python script	python3	absolute server.py path	dependency environment가 따로 필요
published CLI tool	uvx	version을 포함한 package·command	isolated tool environment, package가 executable을 제공해야 함

uv run은 project environment를 확인·동기화한 뒤 command를 실행한다. uvx는 uv tool run의 alias이며 project와 격리된 tool environment를 사용한다. 따라서 “개발은 uv, 배포는 무조건 uvx”가 아니라 server가 project source인지, 배포된 CLI artifact인지로 고른다.

Node.js 실행 패턴

목적	command	args 예시	주의점
compiled artifact 직접 실행	node	absolute build/index.js path	가장 단순한 process tree
package script 실행	npm	run, start, --prefix, absolute project path	script와 working directory 확인
registry CLI 실행	npx	pinned package spec와 arguments	package download·실행 신뢰 경계 확인

local MCP server는 node로 build artifact를 직접 가리키면 어떤 file이 실행되는지 가장 분명하다. npm run도 가능하지만 package.json script, current directory, lifecycle environment가 한 층 더 생긴다.

현재 Amazon Q CLI에서 확인할 것

Amazon Q Developer CLI는 local process server뿐 아니라 HTTP remote server도 지원한다. remote server는 command·args가 아니라 type: "http", url과 OAuth flow를 사용할 수 있다.

현재 상태 확인은 설치된 CLI가 제공하는 read-only list·status command로 한다.

qchat mcp list
qchat mcp status

등록·교체·삭제는 user configuration을 변경하는 작업이다. 이름이 같은 server를 replace할 수 있으므로 실행 전 대상 agent와 server name, 기존 설정 backup을 확인한다.

연결 실패를 좁히는 순서

1. command executable이 host environment의 PATH에서 보이는가
2. args의 source·build artifact와 absolute path가 실제로 존재하는가
3. 같은 command와 arguments를 terminal에서 실행하면 즉시 exit하는가
4. stdio server가 stdout에 일반 log를 쓰고 있지 않은가
5. dependency lock와 runtime version이 실행 환경에 맞는가
6. host status에 load·initialization error가 남는가

credential을 args에 직접 넣으면 process listing과 log에 노출될 수 있다. host가 지원하는 environment·secret 전달 방식과 최소 권한을 사용한다.

네 실행기의 역할은 uv·uvx·npm·npx 차이, 현재 SDK로 동작하는 최소 server는 Python·TypeScript Hello World MCP에서 확인할 수 있다.

참고 자료

• Amazon Q Developer: MCP configuration in the CLI
• Model Context Protocol: Build an MCP server
• uv: Tools
• npm Docs: npx