Claude Code 에 바른 MCP 등록하기

Claude Code(터미널용 AI 코딩 도구)에 바른 MCP 서버를 등록하면, 대화 중에 모델이 직접 바른을 호출해 한국어 형태소 분석과 맞춤법 검사를 수행합니다.

준비물

바른 API 키 — 발급과 사용량은 클라우드에서 사용하기를 참고하세요.
엔드포인트 주소 — 바른 클라우드는 https://api.bareun.ai:443/mcp 입니다. 맞춤법 검사기를 직접 설치한 경우에는 그 서버 주소의 /mcp(예: http://localhost:5656/mcp)를 씁니다. MCP 는 맞춤법 검사기가 포함된 바른에서만 제공되며, 형태소 분석 전용 설치본에는 /mcp 가 없습니다.

등록 방법

터미널에서 한 줄로 추가합니다. 인증은 아래 두 가지 중 하나를 고르세요.

claude mcp add --transport http bareun https://api.bareun.ai:443/mcp \
  --header "api-key: 발급받은_API_키"

헤더로 API 키를 직접 넘기는 방식입니다. 별도의 로그인 단계가 없어 가장 간단합니다.

헤더 없이 주소만 등록합니다.

claude mcp add --transport http bareun https://api.bareun.ai:443/mcp

이후 대화에서 /mcp 를 입력하면 바른 서버에 로그인(authenticate) 하라는 안내가 나타납니다. 브라우저가 열리면 바른 API 키를 입력하세요. 한 번 로그인하면 Claude Code 가 발급된 인증 정보를 보관해 다음부터는 다시 입력하지 않아도 됩니다.

연결 확인

claude mcp list 로 bareun 의 연결 상태를 확인합니다.
대화 중 /mcp 를 입력하면 등록된 서버와 도구 목록(analyze_syntax·tokenize· list_pos_tags·correct_grammar)이 보입니다.
"이 문장을 바른으로 교정해 줘" 처럼 요청하면 모델이 바른을 호출합니다.

프로젝트 단위로 공유하기

claude mcp add 에 --scope project 를 주면 등록 정보가 프로젝트의 .mcp.json 에 저장되어 팀원과 함께 쓸 수 있습니다. 이때 API 키는 직접 넣지 말고 환경변수로 관리하는 것을 권장합니다.

문제가 생기면

도구가 안 보이나요? 주소 끝에 /mcp 가 붙었는지, --transport http 를 줬는지 확인하세요.
권한 오류(401)가 나나요? API 키가 올바른지, 헤더 방식이라면 api-key: 뒤에 실제 키가 들어갔는지 확인하세요. OAuth 방식이라면 /mcp 로 다시 로그인해 보세요.
맞춤법 교정(correct_grammar)이 없나요? MCP 는 맞춤법 검사기가 포함된 바른에서만 제공됩니다. 형태소 분석 전용 서버에는 /mcp 엔드포인트가 없습니다.

자주 묻는 질문

Q. 헤더 방식과 OAuth 로그인 중 무엇을 써야 하나요?

둘 다 같은 바른 API 키로 인증합니다. 빠르게 붙이려면 헤더 방식이 간단하고, 키를 설정 파일에 남기고 싶지 않다면 OAuth 로그인이 편리합니다.

Q. 맞춤법 검사기를 직접 설치한 경우에도 등록할 수 있나요?

네. 맞춤법 검사기가 포함된 바른을 설치했다면, 엔드포인트만 그 서버 주소의 /mcp(예: http://localhost:5656/mcp)로 바꾸면 됩니다. 단, 형태소 분석 전용 설치본에는 /mcp 엔드포인트가 없어 MCP 를 쓸 수 없습니다.