MCP 서버 alwaysLoad 옵션으로 툴 검색 지연 없애기 | Playbook Tip

MCP 서버를 붙여서 쓰다 보면, 툴을 실제로 호출하기 전에 Claude가 "어떤 툴이 있는지 찾아보는" 단계를 거치는 걸 느낄 때가 있어요. 자주 쓰는 서버인데도 매번 tool-search를 타는 게 진짜 거슬리더라고요. 특히 DB 쿼리 툴이나 파일 시스템 서버처럼 거의 모든 대화에서 쓰는 서버라면 이 지연이 쌓여요.

Claude Code v2.1.121에서 alwaysLoad 옵션이 생겼어요. MCP 서버 설정에 "alwaysLoad": true를 넣으면, 그 서버의 툴 전체가 tool-search deferral을 건너뛰고 세션 시작부터 바로 올라와요. 따로 툴을 찾는 과정이 없으니 첫 응답이 눈에 띄게 빨라져요.

준비물

Claude Code v2.1.121 이상
이미 설정해둔 MCP 서버 하나 이상 (전역은 ~/.claude.json, 프로젝트별은 루트의 .mcp.json)

스텝

1. MCP 설정 파일 열기

MCP 서버 설정은 ~/.claude/settings.json이 아니라 별도 파일에 있어요. 헷갈리기 쉬운 부분이라 한 번 짚고 가요.

전역 MCP 서버: ~/.claude.json (홈 루트, .claude/ 폴더 안이 아님)
프로젝트 MCP 서버: 프로젝트 루트의 .mcp.json

~/.claude/settings.json은 권한·훅·환경변수만 담당하고 mcpServers 항목을 인식하지 않아요. 자세한 건 설정 문서 이슈 #4976 참고.

# 전역 설정
code ~/.claude.json

# 또는 프로젝트별 설정
code .mcp.json

2. alwaysLoad 옵션 추가

기존 MCP 서버 항목에 "alwaysLoad": true를 넣으면 돼요. 이 옵션이 없으면 Claude가 필요할 때만 툴을 로드하는 기본 동작을 해요. true로 켜두면 해당 서버 툴이 항상 메모리에 올라와 있어요.

{
  "mcpServers": {
    "my-database-server": {
      "command": "npx",
      "args": ["-y", "@myorg/mcp-db-server"],
      "env": {
        "DB_URL": "<YOUR_DB_URL>"
      },
      "alwaysLoad": true
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
      "alwaysLoad": true
    }
  }
}

자주 안 쓰는 서버는 굳이 alwaysLoad를 켤 필요 없어요. 쓸 때만 로드되는 게 오히려 가볍거든요.

3. Claude Code 재시작

설정 파일을 저장한 뒤 Claude Code를 껐다 켜야 반영돼요.

# Claude Code CLI를 쓰고 있다면
claude

스크린샷 필요

Claude Code 세션 시작 직후 MCP 서버가 연결된 상태를 보여주는 화면 또는 툴 목록이 표시된 상태

id: mcp-server-status

확인 방법

세션을 열고 바로 MCP 툴을 호출해보면 돼요. tool-search 없이 즉시 응답이 오면 적용된 거예요. /mcp 명령으로 현재 연결된 서버 상태도 볼 수 있어요.

# Claude Code 내에서
/mcp

alwaysLoad가 적용된 서버는 세션 시작부터 connected 상태로 잡혀 있어요.

응용

alwaysLoad는 서버 단위로 켜고 끌 수 있어요. 팀 공유 설정이라면 프로젝트 루트의 .mcp.json에 넣고 커밋해두면, 팀원 모두 같은 동작을 하게 돼요. 개인 서버(API 키가 들어간 것)는 전역 ~/.claude.json에만 넣는 게 안전해요.

트러블슈팅

설정 저장 후에도 변화가 없다면 JSON 문법 오류가 있을 가능성이 높아요. 쉼표 하나 빠진 게 전체를 무효로 만들기도 하거든요. cat ~/.claude.json | python3 -m json.tool (전역) 또는 cat .mcp.json | python3 -m json.tool (프로젝트)로 파싱 오류를 바로 잡을 수 있어요.

alwaysLoad를 켠 서버가 많아지면 세션 시작 시간이 살짝 늘어날 수 있어요. 진짜 매번 쓰는 서버에만 적용하는 게 낫고, 가끔 쓰는 건 기본값(tool-search)으로 두는 편이 균형이 맞아요.

이 설정 하나로 자주 쓰는 MCP 서버는 세션 열자마자 바로 쓸 수 있게 돼요.

준비물

스텝

1. MCP 설정 파일 열기

2. alwaysLoad 옵션 추가

3. Claude Code 재시작

확인 방법

응용

트러블슈팅

참고 출처