claude mcp add로 MCP를 실운용한 기록 — 설정·목록·삭제의 모든 커맨드와 막히는 부분

• claude mcp add의 구문 (두 번째 인자 이후에 무엇을 쓸 것인가)
• 추가 후의 확인 방법 (claude mcp list) 및 삭제 (claude mcp remove)
• 스코프 (Scope, 프로젝트 로컬 vs 글로벌) 선택 방법
• 설정 파일의 저장 위치

환경: Claude Code (CLI), 라코 키워드 (Rakko Keyword) MCP (월 2,475엔)

조작	커맨드
추가	claude mcp add <name> <실행 커맨드> [인자...]
...	--scope global을 add에 붙임

막히는 부분은 "<실행 커맨드>에 무엇을 쓸 것인가"뿐이며, 이는 접속하려는 MCP 서버의 공식 README에 기재되어 있다.

claude mcp add <name> <command> [args...]

<name>: Claude Code 내에서 참조하기 위한 임의의 식별자 (예: rakko-keyword)

• <command>: MCP 서버의 실행 커맨드 (npx, python, node 등)
• [args...]: 실행 커맨드에 대한 인자 (공식 README에 적힌 대로 작성)

인자에 -가 포함된 경우에는 --를 구분자로 넣는다.

# -- 를 사용하는 패턴 (인자가 -로 시작할 때)
claude mcp add rakko-keyword -- <공식 실행 커맨드>
# 심플한 npx 계열 MCP의 경우
...

claude mcp list

추가 후에는 반드시 이것으로 확인한다. 여기에 표시되면 설정 완료. 표시되지 않으면 claude mcp add 커맨드를 다시 확인한다.

claude mcp remove <name>

<name>은 claude mcp list에서 표시되는 서버 이름과 일치시킨다.

# 프로젝트 로컬 (기본값)
claude mcp add <name> <command>
# 글로벌 (모든 프로젝트에서 사용)
...

용도	스코프 (Scope)
특정 프로젝트 전용	기본값 (생략)
모든 프로젝트에서 매번 사용	--scope global

스코프 (Scope)	저장 위치
프로젝트 로컬	{프로젝트 루트}/.claude/mcp.json
글로벌	~/.claude/mcp.json

인증 정보가 포함된 MCP는 로컬 스코프로 설정하고, .claude/를 .gitignore에 추가해 둔다.

Q: <command>에 무엇을 써야 할지 모르겠다

A: 접속하려는 MCP 서버의 공식 README의 "설치 / 실행" 섹션을 본다. Claude Code 측의 문제가 아니라, MCP 서버마다 실행 커맨드가 다르다.

Q: 추가 후에 Claude Code에서 툴이 보이지 않는다

A: Claude Code를 재시작한다. 설정은 실행 시에 로드되기 때문에, mcp.json을 변경한 후에는 재시작이 필요하다.

기존의 "MCP인가 CLI인가 API 직접 호출인가"는 판단 기준에 관한 기사로 작성했다. 하지만 GSC에서 "api 직접 호출" 쿼리로 9 임프레션·이탈률 100%라는 수치가 나왔다. 판단 기준은 이해하더라도 실제 설정에서 막히는 수요가 따로 있다고 판단하여 이 기사를 작성했다.

AI 툴을 업무에 도입하는 설계 실험 로그를 쓰고 있습니다. https://masatoman.net