본문 바로가기
M MCP모아
튜토리얼

Windsurf MCP 설정 완벽 가이드 — Cascade에 서버 추가부터 오류 해결까지

Windsurf(구 Codeium) Cascade에 MCP 서버를 연결하는 전 과정을 안내합니다. mcp_config.json 위치·UI 메뉴 설정·수동 편집·환경변수·spawn error 등 흔한 오류 해결과 팀 공유까지 한 편으로 정리했습니다.

Windsurf 에디터의 MCP 설정 파일과 서버 연결 흐름을 보여주는 개요 이미지

Windsurf 에디터에서 MCP(Model Context Protocol) 서버를 추가하려면 ~/.codeium/windsurf/mcp_config.json 파일에 서버 정보를 JSON으로 작성하고 에디터를 재시작하면 됩니다. Windsurf 0.30 버전부터 MCP가 공식 지원되며, Cascade AI 탭에서 바로 MCP 도구를 호출할 수 있습니다. 이 가이드는 설정 파일 위치 확인부터 UI 메뉴 설정과 수동 편집, 그리고 spawn error를 포함한 오류 해결까지 실제 동작하는 예시와 함께 안내합니다.

Windsurf MCP가 필요한 이유

Windsurf(구 Codeium Wave)는 AI 코드 에디터로, 내장 AI 탭인 Cascade에서 대화와 코드 작업을 동시에 수행합니다. Cascade는 코드 작성을 넘어 터미널 실행·파일 검색·외부 도구 호출까지 지원하는 멀티스텝 AI 에이전트인데, 이 외부 도구 연결 표준이 바로 MCP입니다. MCP 서버를 연결하면 Cascade가 직접 처리하지 못하는 작업—파일 시스템 접근, 한국 공문서(.hwp/.hwpx) 읽기, 사내 데이터베이스 조회, 공공 API 호출 등—을 서버 형태로 추가할 수 있습니다.

MCP가 없으면 Cascade는 에디터 내 컨텍스트에만 의존합니다. MCP가 있으면 외부 데이터와 도구를 실시간으로 활용해 더 정확하고 실용적인 답변과 코드를 생성합니다.

개발자 (Windsurf Cascade 채팅)
        │
        ▼
Windsurf Cascade AI
        │
        ▼
MCP 클라이언트 (Windsurf 내장)
        │
        ├─► MCP 서버 A (npx 방식, 로컬 실행)
        ├─► MCP 서버 B (uvx 방식, Python)
        └─► MCP 서버 C (SSE, HTTP URL)
              │
              ▼
        외부 API / 로컬 파일 / 데이터베이스

Windsurf MCP 지원 버전 및 준비물

버전 확인

Windsurf 0.30 이상에서 MCP를 공식 지원합니다. 현재 버전은 에디터 상단 메뉴의 Windsurf > Check for Updates 또는 Help → Check for Updates에서 확인하고 업데이트할 수 있습니다. MCP 지원은 비교적 최신 기능이므로 구버전에서는 관련 메뉴가 표시되지 않을 수 있습니다.

사전 준비물 목록

항목설명필수 여부
Windsurf 0.30+MCP 공식 지원 버전필수
Node.js 18 이상npx 방식 서버 실행용npx 서버 사용 시
Python 3.10 이상 + uvuvx/Python 방식 서버 실행용Python 서버 사용 시
API 키일부 서버 인증용서버에 따라 다름

Node.js 설치 여부는 터미널에서 node -v 및 npx -v로, uv 설치 여부는 uv --version으로 확인합니다. npx 기반 서버가 가장 간단하며, Node.js만 설치돼 있다면 별도의 사전 설치 없이 바로 사용할 수 있습니다.

Windsurf MCP 설정 파일 위치

Windsurf의 MCP 설정 파일은 운영체제별로 다음 경로에 있습니다.

OS설정 파일 경로
macOS~/.codeium/windsurf/mcp_config.json
Windows%USERPROFILE%\.codeium\windsurf\mcp_config.json
Linux~/.codeium/windsurf/mcp_config.json

파일이 없으면 Windsurf를 한 번 실행해 ~/.codeium/windsurf/ 디렉터리를 자동 생성하거나, 수동으로 해당 경로에 빈 JSON 파일을 만들면 됩니다.

Windsurf 설정 UI에서 직접 열기:

설정 파일 경로를 직접 외우지 않아도 됩니다. 두 가지 경로가 있습니다.

  • Windsurf 우측 사이드바에서 Cascade 탭을 선택한 뒤, 상단의 망치(도구) 아이콘 또는 설정 아이콘을 클릭하면 MCP 섹션이 나타납니다. 여기서 Open Config 버튼을 누르면 설정 파일이 에디터에서 열립니다.
  • 또는 상단 메뉴 File → Preferences → Windsurf Settings 에서 Configure MCP 버튼을 클릭하면 Windsurf가 mcp_config.json을 자동으로 찾아 편집기에서 열어 줍니다.

단계별 Windsurf MCP 설정 방법

1단계: Windsurf 버전 및 MCP 지원 여부 확인

먼저 현재 사용 중인 Windsurf가 MCP를 지원하는지 확인합니다.

# Windsurf 버전 확인 (터미널에서)
windsurf --version

0.30 미만이라면 공식 사이트에서 최신 버전을 다운로드하거나 에디터 내 업데이트 기능을 사용합니다.

2단계: MCP 설정 파일 열기

위에서 설명한 UI 버튼(Open Config / Configure MCP)을 쓰거나, macOS 기준으로 터미널에서 직접 파일을 열 수 있습니다.

# macOS — Windsurf로 열기
open -a Windsurf ~/.codeium/windsurf/mcp_config.json

# 또는 기본 편집기 / Windsurf 내장 터미널에서
open ~/.codeium/windsurf/mcp_config.json
code ~/.codeium/windsurf/mcp_config.json

# 디렉터리 내용 확인
ls ~/.codeium/windsurf/

파일이 없으면 새로 생성합니다.

# 디렉토리 생성 및 빈 파일 초기화 (macOS/Linux)
mkdir -p ~/.codeium/windsurf
echo '{"mcpServers": {}}' > ~/.codeium/windsurf/mcp_config.json

3단계: mcpServers 블록에 서버 항목 추가

설정 파일의 기본 구조는 다음과 같습니다.

{
  "mcpServers": {
    "서버이름": {
      "command": "실행_명령",
      "args": ["인수1", "인수2"],
      "env": {
        "환경변수명": "값"
      }
    }
  }
}

npx 방식 서버 추가 예시 (KorDoc):

코르독(KorDoc)은 HWP·HWPX·PDF·XLSX·DOCX 등 한국 공문서를 Markdown으로 변환하는 MCP 서버입니다. API 키 없이 사용할 수 있어 즉시 시작하기 좋습니다.

{
  "mcpServers": {
    "kordoc": {
      "command": "npx",
      "args": ["-y", "kordoc", "mcp"]
    }
  }
}

GitHub: https://github.com/chrisryugj/kordoc

HWP-MCP 서버 추가 예시:

HWP-MCP는 AI 어시스턴트가 한글(.hwp/.hwpx) 문서를 읽고 편집·생성할 수 있게 해줍니다.

{
  "mcpServers": {
    "hwp-mcp": {
      "command": "npx",
      "args": ["-y", "hwp-mcp"]
    }
  }
}

GitHub: https://github.com/treesoop/hwp-mcp

로컬 스크립트 서버 추가 예시:

직접 만든 서버나 사내 서버는 node로 로컬 스크립트를 실행할 수 있습니다.

{
  "mcpServers": {
    "local-server": {
      "command": "node",
      "args": ["/절대/경로/server.js"]
    }
  }
}

여러 서버를 동시에 추가할 때:

{
  "mcpServers": {
    "kordoc": {
      "command": "npx",
      "args": ["-y", "kordoc", "mcp"]
    },
    "hwp-mcp": {
      "command": "npx",
      "args": ["-y", "hwp-mcp"]
    },
    "hwpforge": {
      "command": "npx",
      "args": ["-y", "@hwpforge/mcp"]
    }
  }
}

위 예시에서 한포지(HwpForge)까지 추가하면 한글(HWPX) 문서를 읽고, 쓰고, 변환하는 기능을 Cascade에서 바로 사용할 수 있습니다. HwpForge는 KS X 6101 표준을 지원합니다. GitHub: https://github.com/ai-screams/HwpForge

4단계: 환경 변수가 필요한 서버 설정

API 키나 비밀값이 필요한 서버라면 서버 항목 안에 env 키를 추가합니다.

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "패키지명"],
      "env": {
        "MY_API_KEY": "여기에-키-값-입력"
      }
    }
  }
}

민감한 값은 설정 파일에 직접 적기보다 운영체제의 환경 변수로 분리해 관리하는 것을 권장합니다.

5단계: Windsurf 재시작 후 서버 활성화 확인

설정 파일을 저장(Cmd+S 또는 Ctrl+S)한 뒤 Windsurf를 완전히 종료하고 다시 실행합니다. 단순 창 닫기가 아니라 트레이/메뉴바 아이콘까지 포함해 프로세스를 종료해야 합니다(macOS는 Cmd+Q 또는 Dock 아이콘 우클릭 후 종료). 변경 사항이 가벼운 경우 Cascade 패널만 닫았다가 다시 열어도 반영될 수 있습니다.

재시작 후 Cascade 탭을 열면 MCP 서버 목록에 방금 추가한 서버가 나타납니다. 서버 이름 옆에 녹색 점이 표시되면 정상 연결된 것이며, 서버별로 개별 토글이 제공됩니다.

Cascade 패널 MCP 서버 상태 흐름

mcp_config.json 저장
        ↓
  Windsurf 재시작
        ↓
  Cascade 패널 열기
        ↓
  서버 목록 토글 확인
  ┌─────────────────────┐
  │ ✅ kordoc     [ON]  │
  │ ✅ hwp-mcp    [ON]  │
  │ ✅ hwpforge   [ON]  │
  └─────────────────────┘
        ↓
   AI 채팅에서 도구 사용 가능

6단계: Cascade에서 MCP 도구 호출 테스트

연결이 확인됐다면 Cascade 채팅창에서 MCP 도구를 직접 사용해 볼 수 있습니다.

KorDoc 테스트 프롬프트 예시:

~/Documents/보고서.hwpx 파일을 읽어서 주요 내용을 요약해줘.

HWP-MCP 테스트 프롬프트 예시:

현재 디렉토리에 있는 .hwp 파일 목록을 보여주고, 가장 최근 파일의 내용을 마크다운으로 변환해줘.

UI 설정 대신 수동 편집이 유리한 경우

UI 버튼으로 파일을 여는 것도 결국 같은 mcp_config.json을 편집하는 것입니다. 다만 다음 상황에서는 파일을 직접 편집하는 수동 방식이 더 확실합니다.

  • 사내 배포나 자동화 스크립트로 설정 파일을 일괄 배포할 때
  • 환경 변수, 커스텀 인수가 필요한 서버를 등록할 때
  • UI에서 인식하지 못하는 비표준 서버를 추가할 때
  • 설정을 Git으로 버전 관리해 팀원과 공유할 때

수동 설정의 가장 큰 장점은 재현성입니다. JSON 파일 하나만 복사하면 어떤 환경에서도 동일한 MCP 서버 구성을 즉시 재현할 수 있습니다. CI/CD 파이프라인이나 개발 컨테이너 설정에도 그대로 활용할 수 있어 팀 단위 개발 환경 표준화에 적합합니다.

Windsurf MCP 서버 유형 비교

Windsurf는 두 가지 MCP 전송 방식을 지원합니다.

방식설정 키특징사용 예
stdiocommand + args로컬 프로세스 실행, 가장 일반적npx, uvx, python, node
SSEurlHTTP 엔드포인트 연결원격 MCP 서버

SSE 방식 설정 예시:

{
  "mcpServers": {
    "remote-server": {
      "url": "https://example.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

대부분의 오픈소스 MCP 서버는 stdio 방식입니다. SSE 방식은 팀 공유 서버나 클라우드 배포 서버에서 사용합니다.

데이터 흐름과 보안

stdio 방식 MCP 서버는 Windsurf가 직접 자식 프로세스로 실행합니다. 따라서 서버는 사용자 컴퓨터에서 동작하며, 코드나 파일이 외부 클라우드로 전송되지 않습니다(서버 자체가 외부 API를 호출하는 경우는 제외).

Cascade 에이전트
    │
    ├─ 도구 호출 요청 (JSON-RPC)
    │
    ▼
MCP 서버 프로세스 (로컬 실행)
    │
    ├─ 파일 시스템 / 외부 API / DB 접근
    │
    ▼
결과 반환 → Cascade가 답변에 통합

흔한 오류와 해결 방법

JSON 문법 오류: 서버가 로드되지 않음

MCP 설정 파일은 JSON 형식이라 쉼표 하나, 따옴표 하나가 빠져도 전체가 로드되지 않습니다. 특히 마지막 항목 뒤에 쉼표를 남기는 trailing comma, 따옴표 불일치, 중괄호 불일치가 흔합니다.

확인 방법:

# macOS/Linux에서 JSON 유효성 검사
cat ~/.codeium/windsurf/mcp_config.json | python3 -m json.tool

오류가 없으면 정상 파싱된 JSON이 출력됩니다. 온라인 검사기인 jsonlint.com에 파일 내용을 붙여 넣어 확인할 수도 있습니다.

npx 명령 실행 실패 / spawn error

command not found: npx, spawn error, ENOENT 오류는 Node.js가 설치되지 않았거나 PATH에 등록되지 않은 경우입니다.

# Node.js / npx 설치 확인
node -v
npx -v

버전이 출력되지 않으면 nodejs.org에서 LTS 버전을 설치하세요. 설치 후에도 Windsurf가 PATH를 인식하지 못하면 command 값에 npx 전체 절대 경로를 지정합니다.

# npx 절대 경로 확인
which npx
{
  "mcpServers": {
    "kordoc": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "kordoc", "mcp"]
    }
  }
}

가장 빠른 진단법은 터미널에서 mcp_config.json에 입력한 것과 동일한 명령어를 직접 실행해 오류 메시지를 먼저 확인하는 것입니다.

서버가 연결됐다가 바로 끊김

MCP 서버 프로세스가 시작 직후 종료되는 경우입니다. 주로 의존 패키지 오류나 환경변수 누락이 원인입니다. 터미널에서 직접 실행해 오류 메시지를 확인합니다.

# KorDoc 직접 실행 테스트
npx -y kordoc mcp

# HWP-MCP 직접 실행 테스트
npx -y hwp-mcp

Windows에서 경로 문제

Windows에서 %USERPROFILE% 환경변수가 올바르게 해석되지 않는 경우, 전체 경로를 직접 입력합니다.

C:\Users\사용자이름\.codeium\windsurf\mcp_config.json

PowerShell에서는 echo $env:USERPROFILE로 실제 경로를 확인할 수 있고, 탐색기 주소창에 %USERPROFILE%\.codeium\windsurf를 입력하면 폴더로 바로 이동할 수 있습니다.

증상별 진단표

증상점검 사항
목록 자체가 비어 있음JSON 파일 경로 오타, 문법 오류
서버가 표시되나 빨간 점(오프라인)패키지명 오타, 네트워크 문제
토글이 켜지지 않음Node.js 미설치, 권한 문제
재시작해도 변화 없음트레이까지 완전 종료 안 됨
API 키 오류env 설정 누락

그래도 해결되지 않으면 Windsurf 로그 파일(~/.codeium/windsurf/logs/)에서 오류 메시지를 확인하고, Cascade 탭 상단의 새로고침 버튼으로 MCP 서버 목록을 갱신해 보세요.

한국어 개발 환경에서 유용한 MCP 서버 추천

Windsurf를 사용하는 한국 개발자라면 아래 MCP 서버들이 특히 유용합니다. 모두 API 키 없이 즉시 사용할 수 있습니다.

서버주요 기능설치 명령API 키
코르독(KorDoc)HWP·PDF·DOCX → Markdown 변환npx -y kordoc setup불필요
HWP-MCP한글 문서 읽기·편집·생성npx -y hwp-mcp불필요
한포지(HwpForge)HWPX 문서 AI 에이전트 연동(KS X 6101 표준)npx -y @hwpforge/mcp불필요

이 세 서버를 등록하면 Windsurf의 Cascade AI가 HWP, HWPX, PDF, XLSX, DOCX 파일을 직접 읽고 분석하거나 변환할 수 있습니다. 예를 들어 공공기관에서 받은 HWP 보고서를 열어 핵심 수치를 추출하거나, XLSX 데이터를 Markdown 표로 변환해 문서에 삽입하는 작업을 자연어 지시만으로 처리할 수 있습니다. 더 많은 개발 도구 카테고리 MCP 서버도 탐색해 보세요.

자주 묻는 질문

Windsurf에서 MCP 설정 파일은 어디에 있나요?

macOS는 ~/.codeium/windsurf/mcp_config.json, Windows는 %USERPROFILE%\.codeium\windsurf\mcp_config.json에 위치합니다. Cascade 패널 상단의 MCP 섹션 Open Config 버튼이나 Windsurf Settings 메뉴의 Configure MCP를 누르면 IDE가 직접 파일을 열어 주므로 경로를 외울 필요는 없습니다.

Windsurf에서 지원하는 MCP 서버 유형은 무엇인가요?

stdio 방식(npx, uvx, python, node 등 로컬 프로세스)과 SSE(서버-전송 이벤트, HTTP URL) 방식을 모두 지원합니다. 대부분의 공개 MCP 서버는 stdio 방식입니다.

MCP 서버를 추가했는데 Cascade에 도구가 안 보입니다. 어떻게 하나요?

JSON 문법 오류(특히 trailing comma)와 경로 오타, Node.js/Python 미설치가 주된 원인입니다. python3 -m json.tool이나 jsonlint.com으로 문법을 검사하고, 터미널에서 설치 명령을 직접 실행해 패키지 설치 여부를 확인한 뒤 Windsurf를 트레이 아이콘까지 완전히 재시작하세요.

MCP 서버 연결 중 ‘spawn error’가 발생하면?

command 경로가 PATH에 등록돼 있지 않거나 실행 파일이 없는 경우입니다. Node.js(npx 사용 시) 또는 Python(uvx 사용 시)이 PATH에 있는지 node -v, npx -v로 확인하고, 터미널에서 같은 명령어를 직접 실행해 오류 메시지를 먼저 확인하세요. 필요하면 command에 npx 절대 경로를 지정합니다.

여러 MCP 서버를 동시에 등록할 수 있나요?

네, mcpServers 객체에 서버별로 고유한 키 이름을 부여해 나열하면 됩니다. Windsurf는 등록된 모든 서버를 Cascade 패널에 표시하며, 서버별로 개별 토글을 제공합니다.

Claude Desktop MCP 설정을 Windsurf에 그대로 복사할 수 있나요?

기본 구조(mcpServers 객체 안에 command·args·env 지정)는 거의 동일하게 사용할 수 있습니다. 다만 파일명과 위치가 다릅니다. Claude Desktop은 ~/Library/Application Support/Claude/claude_desktop_config.json(macOS 기준)을 수동 편집하지만, Windsurf는 IDE 내 메뉴에서 직접 열 수 있어 더 편리합니다.

Windsurf Cascade MCP는 무료로 사용할 수 있나요?

Windsurf(Codeium) 자체는 무료 플랜을 제공하며, MCP 연결 기능도 무료입니다. 다만 연결하는 MCP 서버가 외부 유료 API를 사용하는 경우 해당 비용은 사용자가 직접 부담합니다.

API 키가 필요 없는 MCP 서버도 있나요?

네, 이 가이드에서 소개하는 KorDoc, HWP-MCP, HwpForge는 모두 API 키 없이 사용할 수 있습니다. 파일 변환·읽기를 로컬에서 처리하기 때문입니다.

다음 단계

Windsurf MCP 설정이 완료됐다면 바로 MCP 도구를 Cascade에서 활용해 보세요. 한국 공문서 처리에는 코르독(KorDoc), HWP-MCP, 한포지(HwpForge)를 바로 추가해 한글 파일을 AI로 분석하고 변환할 수 있습니다.

더 많은 MCP 서버를 찾고 싶다면 전체 서버 목록이나 개발 도구 카테고리를 방문하거나, 가이드 목록에서 다른 에디터 MCP 설정 가이드도 확인해 보세요. 직접 만든 MCP 서버가 있다면 MCP모아에 등록해 한국 개발자 커뮤니티와 공유할 수 있습니다.

이 글과 관련된 MCP 서버