포스트

Serena MCP 연결의 경계 — 실행 파일·프로젝트·클라이언트 세션 구분하기

Serena를 Claude Code·Codex·OpenCode에 연결할 때 실행 파일의 경로, 프로젝트 선택, 클라이언트별 context와 세션을 구분하고 다중 에이전트의 공유 범위를 살펴본다.

Serena MCP 연결의 경계 — 실행 파일·프로젝트·클라이언트 세션 구분하기

관련: AI 개발 지형의 MCP 갈래 · 개념은 MCP 개념 정리 · 장애 대응은 Serena 트러블슈팅

Serena는 코드베이스의 심볼과 구조를 이해해 검색·편집할 수 있도록 돕는 코딩 에이전트 도구다. 기본적으로 언어 서버(Language Server)를 사용해 심볼 단위로 코드를 읽고 고치며, Claude Code·Codex·OpenCode 같은 MCP 클라이언트와 연결할 수 있다.

Serena를 여러 클라이언트에서 쓸 때 문제는 설치 하나로 끝나지 않는다. 실행 파일을 공유하는 것, 같은 프로젝트 파일을 보는 것, 에이전트의 세션을 공유하는 것은 각각 다른 일이다. 이 글은 그 경계를 실제 연결 예시로 설명한다. 설치·CLI의 전체 문법은 Serena 공식 사용 문서를 따른다.

1
2
3
4
5
6
7
8
9
Serena 실행 환경 준비
  ↓
프로젝트 지정·인덱싱
  ↓
MCP 클라이언트에 등록
  ↓
연결 확인
  ↓
심볼 검색·편집에 사용

1. 가장 간단한 실행: uvx

로컬에 Serena 저장소를 직접 클론하지 않아도 uvx로 실행할 수 있다.

1
2
uvx --from git+https://github.com/oraios/serena \
  serena start-mcp-server

Claude Code에서 현재 프로젝트에 바로 등록하려면 프로젝트 루트에서 다음처럼 실행한다.

1
2
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena \
  serena start-mcp-server --context claude-code --project "$(pwd)"
  • --context claude-code: Claude Code 환경에 맞는 도구 구성을 사용한다.
  • --project "$(pwd)": 현재 디렉터리를 Serena 프로젝트로 지정한다.

2. 설치해서 여러 클라이언트에서 공용으로 쓰기

Claude Code·Codex·OpenCode에서 같은 Serena 실행 파일을 쓰고 싶다면 uv tool로 설치할 수 있다.

1
2
uv tool install serena-agent
SERENA="$(uv tool dir --bin)/serena"

여기서 중요한 것은 실행 파일의 절대경로다. 터미널에서는 serena가 실행되더라도 GUI 애플리케이션이나 이미 실행 중인 에이전트가 셸의 PATH를 그대로 상속하지 않을 수 있다. MCP 설정에는 실제 실행 파일 경로를 넣는 편이 안전하다.

CLI에서 되는 serena가 MCP에서는 실행되지 않는다면 클라이언트가 대화형 셸의 PATH를 상속하는지 먼저 확인한다. 사용자 범위로 한 번 등록해 여러 프로젝트를 쓰더라도, 클라이언트마다 실행 명령과 전송 방식(stdio 또는 HTTP)이 같다는 보장은 없다. 터미널에서 얻은 uv tool dir --bin의 결과를 설정에 실제 절대경로로 넣고 각 클라이언트를 재시작해 연결을 확인한다. 동일한 바이너리를 설치해도 MCP 세션이 하나로 합쳐지는 것은 아니다.

3. 설정과 프로젝트

Serena 설정은 크게 전역 설정과 프로젝트 설정으로 나뉜다.

  • 전역 설정: ~/.serena/serena_config.yml
  • 프로젝트 설정: 프로젝트 루트의 .serena/project.yml
  • 실행 옵션: --context, --mode, --project, --project-from-cwd 등

CLI 기반 에이전트에서 현재 작업 디렉터리를 기준으로 프로젝트를 자동 찾고 싶다면 --project-from-cwd를 사용할 수 있다. Serena는 상위 디렉터리를 탐색하면서 가까운 .serena/project.yml 또는 .git 경계를 프로젝트로 선택한다.

프로젝트 활성화와 인덱싱

1
2
serena activate_project --project /path/to/my_project
serena project index

인덱싱은 큰 코드베이스의 첫 탐색 비용을 줄이는 데 도움이 된다. Serena는 언어 서버를 이용해 코드를 이해하므로 언어별 런타임이나 프로젝트 상태에 따라 첫 분석 시간이 달라질 수 있다.

4. Claude Code와 연결

프로젝트별 등록

앞의 uvx 예시는 실행할 프로젝트를 --project로 고정한다. 공유 설정이 필요하면 Claude Code의 등록 Scope도 함께 선택한다. Serena의 프로젝트 선택과 MCP 클라이언트의 설정 Scope는 다른 축이다. 한쪽만 사용자 범위로 바꾼다고 모든 작업 디렉터리의 프로젝트가 자동으로 바뀌지는 않는다.

사용자 범위 등록

설치한 Serena를 여러 프로젝트에서 공용으로 사용하려면 현재 디렉터리에서 프로젝트를 찾도록 등록할 수 있다.

1
2
claude mcp add --scope user serena -- \
  "$SERENA" start-mcp-server --context claude-code --project-from-cwd

Claude Code에서 /mcp로 serena가 연결됐는지 확인한 뒤 다음처럼 코드 구조를 묻거나 심볼을 찾아본다.

1
2
3
이 프로젝트의 구조를 설명해줘.
authentication 관련 심볼을 찾아줘.
이 클래스의 참조 위치를 찾아줘.

Serena는 기본 설정에서 로컬 웹 대시보드도 띄운다. 기본 주소는 http://localhost:24282/dashboard/index.html이며 포트가 이미 사용 중이면 더 높은 포트를 사용할 수 있다.

5. Codex CLI와 연결

Codex에서는 ~/.codex/config.toml에 Serena MCP 서버를 등록할 수 있다.

1
2
3
4
5
6
7
[mcp_servers.serena]
command = "uvx"
args = [
  "--from", "git+https://github.com/oraios/serena",
  "serena", "start-mcp-server",
  "--context", "codex"
]

Codex를 프로젝트 디렉터리에서 시작한 뒤 Serena에 현재 디렉터리를 활성화하도록 요청한다.

1
Activate the current dir as project using serena

Serena 공식 문서에서 Codex에는 codex context를 사용하도록 안내한다. 대시보드가 자동으로 열리지 않으면 브라우저에서 직접 로컬 대시보드 주소를 열 수 있다.

6. OpenCode와 연결

OpenCode의 opencode.json 또는 opencode.jsonc에 로컬 MCP 서버를 추가한다. 설치한 Serena의 실제 절대경로를 사용하는 편이 안전하다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "serena": {
      "type": "local",
      "command": [
        "/absolute/path/to/serena",
        "start-mcp-server",
        "--context=ide",
        "--project-from-cwd"
      ],
      "enabled": true,
      "timeout": 30000
    }
  }
}

설정을 바꾼 뒤 OpenCode를 재시작하고 연결 상태를 확인한다.

1
opencode mcp list

클라이언트별 context와 설정 형식은 Serena·각 MCP 클라이언트의 버전에 따라 달라질 수 있으므로, 실제 적용 전 현재 공식 문서를 확인한다.

7. 여러 클라이언트를 함께 쓸 때

공유하려는 대상실제 공유 범위
Serena 바이너리같은 실행 파일을 여러 프로세스가 사용 가능
프로젝트 파일·설정·디스크 Memory같은 경로를 보면 읽을 수 있음; 수정 충돌은 별도 문제
언어 서버의 활성 상태클라이언트 프로세스별로 다를 수 있음
에이전트 대화·분석 이유별도 세션의 컨텍스트; 자동 동기화되지 않음

이 표는 일반적인 로컬 stdio 연결 기준이다. HTTP로 별도 서버를 공유하는 구성은 인증·서버 상태의 소유권을 추가로 확인한다.

로컬 stdio 연결에서는 일반적으로 각 MCP 클라이언트가 자기 Serena 프로세스를 시작한다. 같은 프로젝트의 파일은 공유하지만 에이전트의 대화와 도구 실행 상태까지 공유하는 것은 아니다.

여러 에이전트가 같은 저장소를 동시에 편집한다면 MCP 프로세스 분리와 Git 작업 분리를 구분해야 한다. 독립 작업은 branch·worktree로 나눠 변경 충돌을 줄이는 편이 안전하다.

공유되는 것은 동일 경로의 소스·프로젝트 설정·디스크에 저장한 Serena memory다. 활성 언어 서버와 대화 맥락은 클라이언트별이므로 다른 에이전트가 파일을 바꾼 이유나 저장한 memory를 자동으로 읽었다고 가정해서는 안 된다. 여러 프로세스가 같은 Java 프로젝트의 JDTLS 작업공간을 사용할 때의 주의점과 상태 확인 과정의 부작용은 Serena 트러블슈팅에 적었다.

8. 문제가 생겼을 때 어느 경계를 볼까

증상먼저 확인할 경계
터미널에서는 되는데 MCP 연결 실패실행 파일 절대경로·환경 변수·클라이언트 PATH
다른 저장소가 활성화됨--project 고정값과 cwd 기반 프로젝트 탐색
도구가 중복되거나 구성 불일치클라이언트별 context와 기본 제공 기능
다른 에이전트의 분석이 전달되지 않음파일 공유와 세션 맥락 공유의 차이

다음 명령은 이 경계를 확인하는 진입점이다. CLI 버전별 계약은 serena --help와 공식 문서에서 확인한다.

명령설명
serena config edit전역 설정 파일 편집
serena start-mcp-serverMCP 서버 실행
serena project index프로젝트 인덱싱
serena activate_project프로젝트 활성화
serena project health-check .프로젝트와 언어 서버 상태 점검

9. 어디에 쓰는가

Serena의 핵심 가치는 단순 파일 검색보다 코드 구조와 심볼 관계를 이용한 탐색·편집에 있다.

1
2
3
4
5
6
7
8
9
10
11
파일명·문자열 검색
  ↓
관련 파일 후보 찾기

Serena
  ↓
심볼 찾기
  ↓
정의·참조 관계 확인
  ↓
필요한 코드 범위만 읽고 편집

따라서 큰 코드베이스에서 특정 클래스·함수의 정의와 참조를 따라가거나, 에이전트가 불필요하게 많은 파일을 읽지 않도록 탐색 범위를 줄일 때 특히 유용하다.

MCP 자체가 왜 필요한지부터 보고 싶다면 Model Context Protocol(MCP) 개념 정리로 돌아가면 된다. 여러 세션이 같은 파일을 편집하는 조율 문제는 병렬 세션의 공유 채널에서 이어진다.

클라이언트별 context·실행 옵션은 Serena 공식 문서를, 실제 Java 언어 서버 충돌·연결 진단은 Serena 트러블슈팅을 참조한다.

이 기사는 저작권자의 CC BY 4.0 라이센스를 따릅니다.