IntelliJ MCP 서버 연동으로 AI에게 코드베이스를 통째로 넘기기

이번 포스팅에서는 IntelliJ MCP 서버 연동에 대해서 정리하고자 한다. MCP라는 프로토콜 자체가 처음이라면 MCP 실전 가이드를 먼저 보고 오는 편이 이해가 빠르다. JetBrains는 IntelliJ IDEA 2025.1에서 AI Assistant에 MCP 클라이언트 기능을 넣었고, 2025.2에서는 IDE 자체를 MCP 서버로 노출하는 플러그인을 번들에 포함시켰다. 덕분에 설정 화면에서 JSON 몇 줄을 붙여넣으면 AI가 build.gradle의 의존성 트리를 직접 읽고, 모듈 구조를 열거하고, 컴파일 에러 목록을 조회한다. 파일을 열어 복사하고 채팅창에 붙여넣던 작업이 통째로 사라진다. 문제는 IntelliJ의 MCP 지원이 방향이 두 개이고 설정 메뉴가 아예 다른 곳에 있다는 점이다. 이 구분을 모르면 엉뚱한 화면을 붙들고 시간을 태운다. 이 글은 그 두 방향을 나눠서 각각의 설정 절차와 실제 사용 감각, 그리고 사내 코드 유출을 막기 위한 접근 제어까지 다룬다.

MCP를 붙이면 IntelliJ에서 정확히 뭐가 달라지나

IntelliJ MCP 서버를 연결하면 AI가 추측을 멈추고 조회를 시작한다. 프로젝트의 의존성 목록, 모듈 구조, 파일별 컴파일 에러, 데이터베이스 스키마를 AI가 도구 호출로 직접 가져오기 때문이다. 컨텍스트를 사람이 떠먹여 주는 구조에서, AI가 필요할 때 스스로 꺼내 보는 구조로 바뀐다. IntelliJ IDEA 2025.2 기준으로 IDE가 외부 에이전트에 노출하는 도구는 Analysis, Database, Debugger, Execution, Search, Terminal 등 열 개 넘는 카테고리에 걸쳐 있다.

차이는 실제 대화에서 즉시 드러난다. MCP가 없는 상태에서 “이 프로젝트에서 Jackson 버전 올려도 되나”라고 물으면 AI는 일반론을 답한다. 반면 IntelliJ MCP 서버를 통해 get_project_dependencies 도구가 열려 있으면 AI는 실제 의존성 트리를 조회한 뒤 어떤 라이브러리가 Jackson을 transitive로 끌어오고 있는지 짚어낸다. 마찬가지로 코드를 수정한 다음 get_file_problems를 호출해 IDE 인스펙션이 잡은 에러를 확인하고, build_project로 빌드를 돌려 실제로 통과하는지까지 본다.

이 구조가 중요한 이유는 검증 루프가 닫히기 때문이다. AI가 코드를 쓰고, IDE가 그 코드를 평가하고, AI가 평가 결과를 읽어 고친다. 사람이 중간에서 복사·붙여넣기 셔틀을 뛸 일이 없다. IntelliJ MCP 서버 연동으로 얻는 건 결국 IDE가 20년 넘게 쌓아 온 정적 분석 능력을 AI가 그대로 쓰게 되는 것이다. 없던 기능이 생기는 게 아니라 이미 있던 걸 다른 쪽에 열어 주는 셈이다.

내 IDE는 클라이언트인가 서버인가

IntelliJ의 MCP 지원은 방향이 두 개이고, 설정 메뉴 위치가 아예 다르다. AI Assistant가 외부 MCP 서버에 접속하는 방향(IDE = 클라이언트)은 Settings | Tools | AI Assistant | Model Context Protocol (MCP)에 있고, IDE가 자기 기능을 외부 에이전트에 노출하는 방향(IDE = 서버)은 Settings | Tools | MCP Server에 있다. 이름은 비슷한데 하는 일이 정반대라, 여기서 대부분이 헷갈린다.

두 메뉴 모두 Tools 하위에 있고 둘 다 MCP라는 단어가 들어간다. 전자는 “IntelliJ 안의 AI Assistant에게 외부 도구를 쥐어 주는” 설정이고, 후자는 “IntelliJ가 가진 도구를 바깥의 AI에게 넘겨주는” 설정이다. 누가 AI 역할을 맡느냐가 갈린다. JetBrains도 이 혼동이 잦다는 걸 알고 두 옵션의 차이를 설명하는 별도 지원 문서를 따로 냈을 정도다.

표에서 보듯 두 방향은 데이터가 흐르는 쪽이 반대다. 방향 A는 AI Assistant를 주력으로 쓰는 사람에게 필요하고, 방향 B는 터미널에서 Claude Code 같은 에이전트를 돌리면서 IntelliJ를 열어 두는 사람에게 필요하다. 둘을 동시에 켜 두는 것도 얼마든지 가능하며, 실제로 그렇게 쓰는 경우가 많다. IntelliJ MCP 서버 설정을 검색했을 때 나오는 문서가 서로 안 맞아 보인다면, 십중팔구 방향이 다른 문서를 보고 있는 것이다.

실습 1: AI Assistant에 외부 MCP 서버는 어떻게 붙이나

방향 A는 Settings | Tools | AI Assistant | Model Context Protocol (MCP)에 JSON을 붙여넣는 것으로 끝난다. transport 선택, JSON 입력, 서버 활성화 순이며 IntelliJ IDEA 2025.1 이상이면 별도 설치가 필요 없다. transport는 STDIO, Streamable HTTP, SSE(레거시) 세 가지를 지원하고, 로컬 프로세스로 도는 서버는 대부분 STDIO를 쓴다.

stdio 방식 JSON은 어떻게 생겼나

가장 기본이 되는 stdio 방식 JSON 구조는 다음과 같다.

{
  "mcpServers": {
    "yourServerName": {
      "command": "path-or-command-to-start-server",
      "args": ["optional-arguments-passed-to-server"]
    }
  }
}

{
  "mcpServers": {
    "yourServerName": {
      "command": "path-or-command-to-start-server",
      "args": ["optional-arguments-passed-to-server"]
    }
  }
}

위 구조에서 mcpServers 아래의 키가 서버 이름이 되고, 이 이름이 AI Assistant 채팅에서 도구를 식별하는 라벨로 쓰인다. command에는 서버를 띄우는 실행 파일 경로나 명령어를 넣고, args에는 그 명령에 전달할 인자를 배열로 나열한다. stdio 방식은 IDE가 해당 프로세스를 자식으로 띄운 뒤 표준 입출력으로 통신하는 구조이므로, command가 PATH에서 찾을 수 있는 명령이거나 절대 경로여야 한다.

원격 서버에 붙을 때는 url을 쓴다

원격에 이미 떠 있는 서버에 붙일 때는 command 대신 url을 쓴다.

{
  "mcpServers": {
    "yourServerName": {
      "url": "https://example.com/mcp"
    }
  }
}

{
  "mcpServers": {
    "yourServerName": {
      "url": "https://example.com/mcp"
    }
  }
}

이 형태는 IDE가 프로세스를 띄우지 않고 지정된 엔드포인트로 HTTP 요청을 보낸다. 팀이 공용으로 운영하는 사내 MCP 서버나 SaaS 벤더가 제공하는 MCP 엔드포인트를 붙일 때 쓰는 방식이다. 로컬 프로세스가 아니므로 실행 환경 문제에서 자유롭지만, 그만큼 어떤 데이터가 외부로 나가는지 사전 검토가 필요하다.

처음 붙여 볼 서버: 공식 filesystem

실제로 처음 붙여 볼 만한 것은 공식 filesystem 서버다.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]
    }
  }
}

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]
    }
  }
}

이 설정은 npx로 filesystem 서버를 즉석에서 받아 실행하고, 마지막 인자로 넘긴 디렉터리를 접근 허용 범위로 선언한다. -y 플래그는 npx가 설치 여부를 되묻지 않게 하는 것이고, 경로 인자는 여러 개를 이어서 나열할 수도 있다. 다만 이 인자를 최종 방어선으로 믿으면 안 된다. 클라이언트가 MCP Roots를 보내는 순간 서버 측 허용 디렉터리 목록은 통째로 대체되기 때문이다. 이 부분은 뒤 보안 섹션에서 다시 짚는다.

설정 화면에서는 JSON 외에도 몇 가지를 함께 지정한다. Working directory는 서버 프로세스가 실행될 기준 디렉터리이고, Server level은 이 서버를 IDE 전역(global)에 둘지 특정 프로젝트 범위에만 둘지 정한다. “Automatically enable new and changed MCP servers” 옵션은 설정이 바뀌거나 새 서버가 추가됐을 때 자동으로 활성화할지를 결정한다. Claude Desktop을 이미 쓰고 있었다면 Import from Claude 버튼으로 기존 설정을 그대로 끌어올 수 있어서, 손으로 JSON을 옮겨 적을 일이 없다.

설정했는데 도구가 안 뜬다면

설정을 다 마쳤는데 AI Assistant가 도구를 안 쓰는 것처럼 보인다면 채팅창의 Codebase 모드 토글부터 확인하는 게 빠르다. 2025.1 출시 당시 JetBrains는 MCP 도구 호출이 Codebase 모드 토글이 켜져 있거나 편집 모드일 때만 동작한다고 안내했다. 현행 AI Assistant MCP 공식 문서에는 이 제약이 명시되어 있지 않고 요청을 처리하며 자동으로 도구를 호출한다고만 되어 있어서, 그사이 조건이 완화됐을 가능성이 있다. 그래도 도구가 안 잡힐 때 제일 먼저 볼 곳인 건 여전하다.

실습 2: IntelliJ를 Claude Code에 통째로 열어주려면

방향 B, 즉 IntelliJ MCP 서버를 바깥으로 여는 설정은 Settings | Tools | MCP Server에서 켠다. IntelliJ IDEA 2025.2부터 MCP Server 플러그인이 번들로 들어오고 기본 활성화되어 있으므로, 별도 설치 없이 이 메뉴만 열면 된다. Claude Code, Claude Desktop, Cursor, VS Code, Codex, Windsurf는 자동 설정을 지원해서 버튼 한 번으로 연결이 끝난다. 터미널에서 에이전트를 여러 개 병렬로 굴리는 구성이라면 Orca로 AI 코딩 에이전트 병렬 실행하기와 같이 보면 그림이 맞는다. 에이전트를 몇 개 띄우든 IDE 쪽 도구 노출은 이 설정 하나를 공유한다.

목록에 없는 클라이언트는 수동으로 붙인다. 설정 화면의 Copy SSE Config, Copy Stdio Config, Copy HTTP Stream Config 버튼 중 하나를 눌러 설정 스니펫을 복사한 뒤, 해당 클라이언트의 MCP 설정 파일에 붙여넣으면 된다. 세 버튼은 각각 다른 transport에 대응하므로 클라이언트가 지원하는 방식에 맞춰 고르면 된다.

연결이 되면 IDE가 어떤 도구를 노출하는지가 본론이다. 카테고리가 열 개를 넘어가고 Database만 해도 열 개 남짓이라 전부 옮기는 건 의미가 없다. 백엔드 작업에서 실제로 손이 가는 것만 추리면 다음과 같다.

Debugger 쪽 도구명이 xdebug_로 시작하는 게 눈에 걸릴 수 있다. xdebug는 원래 PHP 디버거 이름이지만 JetBrains가 IDE 공통 디버거 도구에 이 접두사를 붙였고, IntelliJ IDEA 문서에도 그대로 실려 있다. PhpStorm 전용이 아니므로 Java 프로젝트에서도 동작한다.

목록을 보면 이 방향이 왜 강력한지가 드러난다. 단순 파일 읽기·쓰기를 넘어 Analysis와 Execution 카테고리가 들어 있다는 게 핵심이다. get_file_problems는 AI가 방금 작성한 코드에 대해 IDE 인스펙션이 잡아낸 문제를 직접 확인하게 해 주고, build_project는 실제로 빌드를 돌려 통과 여부를 판정하게 해 준다. Database 카테고리가 붙어 있으면 AI가 list_database_connections로 연결을 확인하고 execute_sql_query로 스키마를 실제로 조회하므로, 엔티티 클래스와 실제 테이블이 어긋나는 문제를 코드만 보고 추측하지 않는다.

이 구조를 두고 Martin Fowler는 Maintainability sensors for coding agents(2026-05-19)에서 에이전트 산출물의 품질을 재는 센서라는 표현을 썼다. 에이전트에게 코드를 시키는 것보다, 에이전트가 자기 산출물을 스스로 측정할 수 있는 계기판을 붙여 주는 게 더 중요하다는 취지다. IntelliJ MCP 서버가 노출하는 Analysis 도구들이 정확히 그 센서에 해당한다. 전체 도구 목록과 옵션은 IntelliJ MCP Server 공식 문서에서 확인할 수 있다.

과거를 아는 사람을 위해 덧붙이면, 예전에는 npx -y @jetbrains/mcp-proxy를 거쳐야 IDE에 붙을 수 있었다. JetBrains/mcp-jetbrains 저장소(963 stars)가 그 프록시를 제공했는데, 2025.2부터 IDE 내장 기능이 그 역할을 대체하면서 해당 저장소는 유지보수 중단 상태가 됐다. 지금 검색해서 mcp-proxy 설정법이 나오면 오래된 문서를 보고 있는 것이므로 그냥 설정 메뉴로 가는 게 맞다.

어떤 MCP 서버부터 붙이는 게 남는 장사인가

백엔드 개발자가 IntelliJ MCP 서버를 처음 붙인다면 filesystem과 git 두 개로 시작하는 게 효율이 가장 좋다. 이 둘만 붙어도 AI가 프로젝트 전체 구조를 훑고 최근 커밋 이력을 읽는 상태가 되며, 나머지 서버는 팀 상황에 따라 필요할 때 추가하면 된다. 공식 서버 모음인 modelcontextprotocol/servers 저장소는 88.5k stars로, 여기 있는 reference 서버부터 훑는 것이 안전하다.

reference 서버 중 실무에서 자주 쓰이는 것은 다음과 같다. Filesystem은 “Secure file operations with configurable access controls”로, npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/files 형태로 실행한다. Git은 “Tools to read, search, and manipulate Git repositories”이며 uvx mcp-server-git으로 띄운다. Fetch는 “Web content fetching and conversion for efficient LLM usage”로 웹 문서를 LLM이 먹기 좋은 형태로 변환해 준다. Memory는 “Knowledge graph-based persistent memory system”이며 npx -y @modelcontextprotocol/server-memory로 실행한다. 그 외에 Sequential Thinking, Time, Everything이 함께 제공된다.

filesystem 서버가 노출하는 도구를 읽기와 쓰기로 나눠 보면 성격이 분명해진다. 읽기 쪽은 read_text_file, read_media_file, read_multiple_files, list_directory, list_directory_with_sizes, search_files, directory_tree, get_file_info, list_allowed_directories가 있고, 쓰기 쪽은 write_file, edit_file, create_directory, move_file이 있다. directory_tree 하나만 있어도 AI가 멀티모듈 프로젝트의 레이아웃을 한 번에 파악하고, read_multiple_files로 관련 클래스를 묶어 읽으므로 파일 하나씩 물어보는 왕복이 사라진다.

추천 순서를 굳이 정하자면 filesystem, git, 그다음이 팀 상황이다. filesystem을 먼저 붙이는 이유는 효용이 즉각적이면서 접근 범위를 명령행 인자 하나로 못 박을 수 있어 위험이 통제되기 때문이다. git을 두 번째로 두는 이유는 blame과 커밋 로그가 붙는 순간 AI가 “이 코드가 왜 이렇게 생겼는지”까지 추론하기 시작해서, 리팩터링 제안의 질이 눈에 띄게 달라지기 때문이다. Memory는 매력적으로 보이지만 팀 전체가 쓰는 컨텍스트를 어디에 저장할지 정하지 않은 채 붙이면 관리 부담만 생기므로, 개인 실험 단계에서는 후순위로 두는 편이 낫다.

사내 코드가 밖으로 새지 않게 하려면

IntelliJ MCP 서버 설정에서 통제 지점은 네 군데다. filesystem 서버의 허용 디렉터리, MCP Server 쪽의 Exposed Tools와 brave mode, 그리고 Server level 범위 설정이다. 이 넷을 잡아 두면 대부분의 로컬 MCP 구성은 사내 정책 안에 들어온다.

먼저 짚어야 할 함정이 있다. filesystem 서버의 접근 제어는 두 가지 방법이 있는데, 이 둘은 나란히 쌓이지 않는다. 첫째는 서버 실행 시 명령행 인자로 허용 디렉터리를 지정하는 방식이고, 둘째는 MCP Roots를 쓰는 방식이다. Roots는 클라이언트가 런타임에 허용 디렉터리를 갱신할 수 있어 서버 재시작이 필요 없고, filesystem 서버 README도 이쪽을 권장한다.

문제는 우선순위다. README는 클라이언트가 Roots를 보내면 서버 측 허용 디렉터리를 “completely replace”한다고 명시한다. 보강이 아니라 교체다. 명령행 인자로 디렉터리 하나만 좁게 물려 뒀더라도 클라이언트가 더 넓은 Roots를 넘기면 그쪽이 이긴다. 실질적인 통제권이 서버가 아니라 클라이언트에 있다는 뜻이므로, 사내 정책을 세울 때 서버 실행 스크립트만 검사하는 방식으로는 구멍이 남는다.

도구 단위로 잠그고 싶다면 Settings | Tools | MCP Server의 Exposed Tools에서 개별 도구의 노출을 끌 수 있다. execute_terminal_command나 쓰기 계열 도구만 골라 내리는 식이라, 뒤에 나올 brave mode보다 훨씬 세밀한 통제 수단이다. 팀 표준을 잡을 때 여기부터 손대는 편이 낫다.

가장 조심해야 할 것은 brave mode다. Settings | Tools | MCP Server의 Command execution 섹션에 있는 “Run shell commands or run configurations without confirmation (brave mode)” 옵션을 켜면 execute_terminal_command가 확인 절차 없이 실행된다. 즉 AI가 판단한 셸 명령이 바로 로컬에서 돌아간다. 편의성은 확실하지만, 에이전트가 정리 작업을 한다며 rm을 섞어 넣는 상황을 상상해 보면 기본값을 그대로 두는 쪽이 합리적이다. 터미널 환경 자체를 손보는 이야기는 Ghostty 터미널 실전 가이드에서 따로 정리한 적이 있다.

Server level을 project 범위로 두는 것에도 실질적 의미가 있다. global로 두면 그 IDE에서 여는 모든 프로젝트에 해당 MCP 서버가 따라붙는다. 사내 코드와 개인 사이드 프로젝트를 같은 IDE에서 오간다면, 사내 전용 서버는 project 범위로 묶어 두는 것이 사고를 줄인다.

MPS 2026.1은 어디까지 열어줬나

IDE가 AI에게 자기 도구를 넘기는 흐름은 IntelliJ에 국한되지 않는다. 2026년 7월 릴리스된 MPS 2026.1은 Projectional Agent Toolkit을 기본 번들·활성화 상태로 넣었고, Claude Code와 OpenAI Codex, JetBrains Junie를 포함해 모든 MCP 호환 클라이언트를 지원한다.

Toolkit은 MPS 프로젝트 전반을 덮는 열두어 개의 툴셋을 제공한다. 솔루션·언어·devkit 열거, 개념 계층 검사, 노드 CRUD, 참조 범위 쿼리, 실행 구성 목록과 실행이 포함된다. 눈에 띄는 건 도구만 넘기지 않는다는 점이다. DSL 작성법을 가르치는 Skills가 같이 딸려 온다. 에이전트에게 “무엇을 할 수 있는지”를 넘어 “이 환경에서 어떻게 하는 게 맞는지”까지 쥐어 주려는 시도로 읽힌다. 자세한 내용은 MPS 2026.1 릴리스 노트에 정리되어 있다.

프로젝셔널 에디터는 일반적인 텍스트 에디터와 작동 방식부터 다른, 상당히 특수한 환경이다. 그런 쪽까지 MCP로 열렸다는 건 IDE가 AI에게 도구를 넘기는 게 실험 단계를 지났다는 신호로 볼 만하다. 적어도 JetBrains는 이 방향에 확신이 있어 보인다.

FAQ

마치며

지금까지 IntelliJ MCP 서버 연동에 대해서 정리해 보았다. 방향 A와 방향 B라는 구분만 머리에 넣어 두면 나머지는 설정 화면에서 JSON을 붙여넣는 단순 작업이다.

솔직히 말하면 이 구분을 몰라서 꽤 헤맸다. Settings | Tools | MCP Server에서 서버를 잘 켜 놓고는 AI Assistant 채팅창에서 도구가 왜 안 뜨냐고 한참을 들여다봤다. 방향이 반대인 메뉴였으니 당연히 안 뜰 일이었는데, 이름이 비슷해서 같은 기능의 다른 진입점이라고 착각했던 것이다.

AI에게 파일 경로를 하나씩 붙여넣던 시절과 비교하면 지금은 정말 편해졌다. 그만큼 IDE가 넘겨주는 권한의 크기도 커졌다. brave mode를 한번 켜 놓고 작업하다가 에이전트가 임시 디렉터리를 정리하겠다며 명령을 만들어 내는 걸 보고 조용히 끈 적이 있다. 허용 디렉터리도 마찬가지다. 명령행 인자에 경로 하나만 박아 두면 그 밖으로는 못 나간다고 믿었는데, Roots가 그 목록을 통째로 갈아치운다는 걸 문서를 다시 읽고서야 알았다. 편의성과 통제 사이의 선은 각자 그어야 하지만, 적어도 그 선이 진짜 어디에 그어져 있는지는 확인하고 시작하는 게 낫다.