🧩 Model Context Protocol (MCP) & Serena MCP 정리

1. MCP란?

MCP (Model Context Protocol) 은 Anthropic(Claude 개발사)이 제안한
AI 모델과 외부 리소스(파일, DB, API 등)가 표준화된 방식으로 상호작용하도록 하는 오픈 프로토콜이다.

💡 핵심 목적

• AI 모델이 외부 시스템의 데이터를 안전하고 일관된 방식으로 접근할 수 있게 함
• 기존의 “커스텀 플러그인/툴 연결 문제(N×M)”를 하나의 통합 인터페이스로 단순화

🧠 주요 특징

| 항목 | 설명 | |——|——| | 통신 방식 | JSON-RPC 2.0 기반 양방향 통신 | | 구조 | 클라이언트(모델) ↔ MCP 서버(리소스 제공자) | | 보안 | 명시적 권한 요청 / 승인 기반 접근 | | 활용 범위 | 파일 읽기, API 호출, 데이터 조회, 코드베이스 분석 등 |

---

2. MCP의 기본 구조

+----------------+
| Claude / LLM   |  ← 클라이언트
+--------+-------+
|
|  JSON-RPC 요청 (MCP 프로토콜)
↓
+--------+-------+
| MCP Server     |  ← 외부 리소스 접근 서버
| (예: Serena)   |
+--------+-------+
|
↓
+----------------+
| Files / DB / APIs |
+----------------+

---

3. Serena MCP란?

Serena MCP는 MCP 표준을 구현한 코드베이스 분석용 서버이다.
Claude Code 또는 Claude Desktop 등과 연동되어,
AI가 프로젝트의 전체 코드를 구조적으로 이해할 수 있게 돕는다.

🧰 Serena MCP의 역할

| 기능 | 설명 | |——|——| | 코드 인덱싱 | 프로젝트 전체 파일을 스캔하고, 함수/클래스 관계를 데이터베이스화 | | 참조 추적 | 함수 호출 관계, 클래스 상속, 변수 참조 등을 추적 | | 빠른 검색 | Claude의 요청에 맞춰 관련 코드나 파일을 즉시 반환 | | 문맥 관리 | 대규모 코드에서 모델이 처리 가능한 범위를 관리 | | MCP 통신 | Claude와 JSON-RPC로 명령/응답 처리 |

---

4. Claude Code + Serena MCP 연결 흐름

사용자 요청
↓
Claude Code (클라이언트)
↓
[MCP 요청]
↓
Serena MCP (서버)
↓
코드베이스 / 파일 시스템

예를 들어 사용자가 다음과 같이 묻는다면:

“UserService 클래스가 어디서 사용되나요?”

1. Claude Code가 MCP 요청을 보냄
2. Serena MCP가 코드베이스를 탐색
3. 호출 위치를 찾아 JSON 응답
4. Claude Code가 자연어로 결과를 요약하여 사용자에게 보여줌

---

5. Serena MCP 설치 요약 (예시)

# 1️⃣ 저장소 클론
git clone https://github.com/oraios/serena
cd serena

# 2️⃣ 의존성 설치 (uv 사용)
uv sync

# 3️⃣ MCP 서버 실행
uv run --directory /path/to/serena serena-mcp-server --context ide-assistant

# 4️⃣ Claude Code에 서버 등록
claude mcp add serena -- \
  uvx --from git+https://github.com/oraios/serena serena-mcp-server --context ide-assistant

⚙️ 설정 파일: ~/.serena/serena_config.yml

web_dashboard: false
read_only: true

---

6. Claude ↔ Serena 연동 설정

🧩 전역 설정 (권장)

Claude Desktop은 MCP 서버 목록을 전역 파일(servers.json)로 관리한다.

Mac 예시 경로:

~/Library/Application Support/Claude/servers.json

Linux 예시 경로:

~/.config/Claude/servers.json

✍️ 예시 설정

{
  "servers": [
    {
      "id": "serena",
      "name": "Serena MCP Server",
      "command": "uv",
      "args": ["run", "--directory", "/Users/you/serena", "serena", "start-mcp-server"],
      "env": {},
      "autoStart": true
    }
  ]
}

Claude를 재시작하면 자동으로 Serena MCP 서버를 감지하고 연결한다.

“Serena MCP Server connected” 메시지가 표시되면 성공 🎉

---

7. 고급 설정 (선택 사항)

🧠 여러 프로젝트에서 다른 Serena 인스턴스 사용하기

기본적으로 servers.json은 전역 설정이지만, 서로 다른 프로젝트별로 다른 Serena 서버를 등록할 수도 있다.

예시

{
  "servers": [
    {
      "id": "serena-dev",
      "name": "Serena (Dev)",
      "command": "uv",
      "args": ["run", "--directory", "/Users/you/dev/serena", "serena", "start-mcp-server"]
    },
    {
      "id": "serena-prod",
      "name": "Serena (Prod)",
      "command": "uv",
      "args": ["run", "--directory", "/Users/you/prod/serena", "serena", "start-mcp-server"]
    }
  ]
}

또는 환경변수 기반으로도 지정 가능하다.

{
  "servers": [
    {
      "id": "serena",
      "name": "Serena (Dynamic)",
      "command": "uv",
      "args": ["run", "--directory", "$SERENA_PATH", "serena", "start-mcp-server"]
    }
  ]
}

# 프로젝트별로 환경변수 설정 후 실행
export SERENA_PATH=/Users/you/myproject/serena
claude &

---

8. 장점 및 주의사항

✅ 장점

• 코드 이해력 향상 (함수 관계, 호출 추적 등)
• 대규모 프로젝트 탐색 속도 개선
• Claude Code의 맥락 품질 향상
• uv 기반 설치로 빠르고 가벼움
• Claude와 자동 통신 (MCP 프로토콜 표준)

⚠️ 주의사항

• 프로젝트에 접근 권한이 있는 경우에만 실행
• read_only 모드 권장 (코드 수정 방지)
• servers.json은 전역 적용이므로, 잘못된 경로 설정 시 Claude 전체에서 에러 발생

---

9. 요약

구분	설명
MCP	모델이 외부 리소스와 통신하기 위한 오픈 프로토콜
Serena MCP	코드베이스 구조를 Claude에 제공하는 MCP 서버
Claude Code	사용자 명령을 이해하고 Serena MCP로부터 데이터 요청
핵심 장점	코드 탐색·리팩토링·맥락 이해 향상
필수 조건	Python + uv 환경, 로컬 서버 실행 권한
연결 방식	Claude ↔ Serena 간 JSON-RPC 기반 양방향 통신
설정 위치	전역: servers.json / 로컬: ~/.serena/config.yml

---

바로 그 내용 섹션 하나 추가하면 딱 좋겠네. 아래 블록을 “10. Codex에 Serena MCP 연동하기” 같은 제목으로 그대로 붙여 넣으면 된다.

---

10. Codex에 Serena MCP 연동하기

Serena MCP는 Claude뿐만 아니라 Codex CLI에서도 그대로 MCP 서버로 사용할 수 있다. Codex는 MCP 클라이언트이기 때문에, ~/.codex/config.toml 에 Serena 서버 실행 커맨드를 등록해 두면 된다.([OpenAI Developers][1])

10.1 사전 준비

1. Codex CLI 설치

npm install -g @openai/codex@latest
codex --version
codex login

1. uv 설치 (Serena 실행용) ([Playbooks][2])

curl -LsSf https://astral.sh/uv/install.sh | sh

# 설치 후 PATH에 추가 (Linux / macOS 예시)
export PATH="$HOME/.local/bin:$PATH"
uvx --version

⚠️ uvx: command not found 가 나오면, Codex가 뜨는 쉘 프로파일(.zshrc, .bashrc 등)에 PATH="$HOME/.local/bin:$PATH" 를 추가해야 한다.

---

10.2 Codex MCP 설정 파일에 Serena 등록

Codex는 MCP 설정을 ~/.codex/config.toml 에 저장한다.([OpenAI Developers][1])

• macOS / Linux: ~/.codex/config.toml
• Windows: C:\Users\<계정>\.codex\config.toml (없으면 직접 생성)

파일에 아래 블록을 추가한다(없으면 새 파일로 만들어도 됨):

[mcp_servers.serena]
command = "uvx"
args = [
  "--from", "git+https://github.com/oraios/serena",
  "serena", "start-mcp-server",
  "--context", "codex"
]

# (옵션) Serena 기동/툴 실행 타임아웃 조정
startup_timeout_sec = 120
tool_timeout_sec = 600

• mcp_servers.serena

  • Codex에서 보이는 서버 이름(원하면 serena-code 등으로 바꿔도 됨).([OpenAI Developers][1])

• command = "uvx"

  • Codex가 MCP 서버를 띄울 때 실행할 명령.

• args = [...]

  • Serena 공식 문서 권장 형태로, Codex 전용 컨텍스트인 --context codex 를 꼭 붙여야 Codex와 호환되게 툴 구성이 잡힌다.([mcpindex.net][3])

---

10.3 Codex에서 연결 확인 및 프로젝트 활성화

1. Codex TUI 실행

codex

1. MCP 서버 연결 상태 확인

Codex TUI 안에서:

/mcp

• serena 가 목록에 보이면 MCP 연결은 성공한 것.([OpenAI Developers][1])

1. 현재 프로젝트를 Serena에 활성화

Serena 공식 가이드에 따라, Codex에서는 대화 안에서 프로젝트를 활성화해야 툴이 제대로 동작한다.([mcpindex.net][3])

Codex에게 이렇게 말해준다:

“Activate the current dir as project using serena”

혹은:

“Use Serena to activate this directory as a project”

• 이 과정을 하지 않으면 Serena 툴이 코드베이스를 제대로 못 본다.
• 한 번 활성화하면 ~/.serena/serena_config.yml 과 <프로젝트>/.serena/project.yml이 생성되어 이후부터는 더 빨리 붙는다.([mcpindex.net][3])

1. 정상 동작 여부 로그 확인 (선택)

문제가 의심되면:

tail -n 200 ~/.codex/log/codex-tui.log

에서 serena 관련 에러가 있는지 확인할 수 있다.([mcpindex.net][3])

---

10.4 Codex + Serena 사용할 때 팁 / 주의사항

• 대시보드 Serena는 기본적으로 http://localhost:24282/dashboard/index.html 에 웹 대시보드를 띄운다. Codex에서 브라우저 자동 오픈은 막힐 수 있으니, 주소를 직접 열어보면 현재 세션/로그를 확인할 수 있다.([mcpindex.net][3])

• 툴 상태가 failed로 보여도 실제론 정상 Codex 쪽 버그로, Serena 툴 실행이 성공했는데도 UI에 failed로 표시되는 경우가 있다. Serena 문서에서도 “에러처럼 보여도 실제로는 잘 동작하니 무시해도 된다”고 명시돼 있다.([mcpindex.net][3])

• 프로젝트 인덱싱(옵션) 큰 레포라면 첫 호출 속도를 위해 한 번쯤 아래를 실행해 두는 걸 권장:

  # 프로젝트 루트에서
  uvx --from git+https://github.com/oraios/serena serena project index
  

  이렇게 해두면 Codex가 Serena 툴을 부를 때 코드 검색/참조 추적이 훨씬 빠르다.([mcpindex.net][3])

---

✨ 한마디로 MCP는 “AI 모델을 외부 리소스와 연결하는 표준 인터페이스”이고, Serena MCP는 그 표준을 활용해 Claude가 “코드베이스를 이해하고 탐색할 수 있게 돕는 로컬 도구 서버”이다.