MCP 서버로 사용하기

Q: 바른 MCP 서버를 쓰려면 새 포트를 열거나 별도 설치가 필요한가요?

아니요. 바른 서버가 이미 열려 있는 같은 주소의 /mcp 경로가 MCP 엔드포인트입니다. 추가 포트나 별도 설치 없이 바로 사용할 수 있습니다.

Q: 형태소 분석 전용 바른에서도 MCP 를 쓸 수 있나요?

아니요. MCP(/mcp 엔드포인트)는 맞춤법 검사기가 포함된 바른에서만 제공됩니다. 형태소 분석 전용 바른에는 /mcp 엔드포인트가 없습니다. 맞춤법 검사기가 포함된 바른에서는 analyze_syntax, tokenize, list_pos_tags, correct_grammar 네 도구가 모두 제공되며, 설치형 맞춤법 검사기에서도 동일하게 사용할 수 있습니다.

Q: 바른 MCP 서버 인증은 어떻게 하나요?

api-key 헤더에 발급받은 API 키를 넣거나, Authorization: Bearer 형식으로 보냅니다. 둘 중 어느 방식이든 사용할 수 있으며, 키가 없으면 요청이 거부됩니다.

Q: 바른 MCP 서버의 버전이나 지원 도구를 어떻게 확인하나요?

bareun://server-info 리소스를 읽으면 서버 버전, 빌드 종류(revision/standard), 활성 도구와 리소스 목록을 한 번에 받을 수 있습니다. 리소스를 지원하지 않는 클라이언트는 resources/read 메서드에 {"uri": "bareun://server-info"} 를 넣어 호출하면 됩니다.

Q: analyze_syntax 도구의 full 과 compact 형식은 어떻게 다른가요?

full 은 형태소, 품사, 위치까지 담은 전체 결과를 돌려주고, compact 는 표층형/품사 를 공백으로 이은 한 줄 요약을 돌려줍니다. 빠르게 읽거나 토큰을 아끼고 싶을 때는 compact 가 편리합니다.

Q: 바른 MCP 에서 품사 코드(NNG, JKS 등)의 뜻은 어떻게 확인하나요?

list_pos_tags 도구를 호출하면 47개 품사 태그의 코드, 이름, 분류를 한 번에 받을 수 있습니다. 같은 내용을 bareun://pos-tags 리소스로도 읽을 수 있어, AI 도구가 분석 결과를 해석할 때 참고 자료로 사용할 수 있습니다.

Q: 바른 MCP analyze_syntax 결과의 위치 값 단위는 어떻게 정하나요?

encoding 옵션으로 정합니다. 기본값은 글자(코드포인트) 수 기준인 utf32 이며, 자바스크립트나 자바에서 처리하면 utf16, Go 나 C++ 에서 처리하면 utf8 로 맞춰 호출하면 됩니다.

바른 MCP 서버로 AI 에이전트에 한국어 능력 더하기

바른은 MCP(Model Context Protocol) 서버로도 동작합니다. MCP 는 Claude·Cursor 같은 AI 도구가 외부 기능을 표준 방식으로 불러 쓰도록 약속한 규격입니다. 바른을 MCP 서버로 연결하면, AI 에이전트가 글을 쓰거나 분석할 때 스스로 바른을 호출해 한국어 형태소 분석과 맞춤법 검사를 수행할 수 있습니다.

왜 MCP 인가요?

대형 언어모델은 한국어 문장의 미묘한 띄어쓰기나 어법을 놓칠 때가 있습니다. 바른을 MCP 도구로 붙여 두면, 에이전트가 필요할 때마다 바른에게 분석·교정을 맡기고 그 결과를 받아 더 정확한 한국어 결과를 만들 수 있습니다.

별도의 포트나 추가 설치는 필요 없습니다. 바른 서버가 열리는 같은 주소의 /mcp 경로가 MCP 엔드포인트입니다.

MCP 는 맞춤법 검사기가 포함된 바른에서 제공됩니다

MCP 기능(/mcp 엔드포인트)은 맞춤법 검사기가 포함된 바른에서만 제공됩니다. 형태소 분석 전용 바른에는 /mcp 엔드포인트가 없습니다. 설치형으로 제공되는 맞춤법 검사기에서도 동일하게 MCP 를 사용할 수 있습니다.

제공하는 도구

맞춤법 검사기가 포함된 바른의 MCP 서버는 다음 도구를 제공합니다.

도구 이름	하는 일	주요 입력
`analyze_syntax`	문장을 어절·형태소로 나누고 품사를 붙입니다(형태소 분석).	`text`(필수), `auto_split_sentence`, `auto_spacing`, `auto_jointing`, `custom_dict_names`, `encoding`, `format`
`tokenize`	문장을 어절(토큰) 단위로 나눕니다.	`text`(필수), `auto_spacing`, `encoding`
`correct_grammar`	맞춤법·띄어쓰기를 교정합니다.	`text`(필수), `custom_dict_names`, 교정 옵션(아래)
`list_pos_tags`	바른이 쓰는 47개 품사 태그 목록(코드·이름·분류)을 돌려줍니다.	(입력 없음)

format 옵션 (analyze_syntax)

full(기본): 형태소·품사·위치까지 담은 전체 결과를 돌려줍니다.
compact: 표층형/품사 표층형/품사 … 형태의 한 줄 요약을 돌려줍니다. 예) 나는 → 나/NP 는/JX

encoding 옵션 (위치 값의 기준)

분석 결과에는 각 형태소가 원문에서 시작하는 위치가 들어 있는데, 이 위치를 어떤 단위로 세는지를 encoding 으로 정합니다. 결과를 받아 처리하는 쪽 언어에 맞추면 됩니다.

utf32(기본): 글자(코드포인트) 수 기준. 파이썬 문자열과 잘 맞습니다.
utf16: 자바스크립트·자바 문자열과 잘 맞습니다.
utf8: 바이트 기준. Go·C++ 와 잘 맞습니다.

교정 옵션 (correct_grammar)

기본값(모두 끔)만으로도 교정이 동작합니다. 아래 옵션을 필요할 때 켜거나 끌 수 있으며, 모두 참/거짓(boolean)으로 지정합니다. 예를 들어 기사 제목을 교정할 때는 treat_as_title 을 켭니다.

옵션	기본값	켜면 일어나는 일
`treat_as_title`	끔	입력을 기사·글의 제목으로 취급해 교정합니다. 제목은 종결 어미·마침표가 없는 등 본문과 규칙이 달라, 제목을 교정할 때 켜면 더 자연스럽습니다.
`disable_split_sentence`	끔	문장 분리를 하지 않습니다. 보통은 입력을 문장 단위로 나눠 교정하는데, 이미 한 문장이거나 줄바꿈을 문장 경계로 쓰고 싶지 않을 때 켭니다.
`disable_caret_spacing`	끔	복합명사 분리(띄어쓰기) 교정을 끕니다. 붙여 쓴 복합명사를 굳이 나눠 띄우지 않게 합니다.
`disable_vx_spacing`	끔	보조 용언 띄어쓰기 교정을 끕니다. ‘도와 주다 → 도와주다’처럼 보조 용언을 붙이는 교정을 적용하지 않습니다.
`enable_limited_punctuation`	끔	제한된 구두점 규칙을 적용합니다. 허용하는 문장 부호 범위를 좁혀 교정합니다.
`disable_confusion`	끔	혼동어 모델을 끕니다. ‘되/돼’, ‘맞히다/맞추다’처럼 헷갈리는 단어를 문맥으로 바로잡는 기능을 호출하지 않습니다(더 빠르지만 혼동어 교정은 빠집니다).
`enable_cleanup_whitespace`	끔	불필요한 공백을 정리합니다(중복 공백 제거 등).
`disable_typo_correction`	끔	오타(오탈자) 교정을 끕니다. 맞춤법 오류 교정 없이 띄어쓰기 등 다른 교정만 적용하고 싶을 때 씁니다.
`enable_sentence_check`	끔	문장 단위 점검을 활성화합니다. 어절 단위를 넘어 문장 전체의 호응 등을 함께 살핍니다.

품사 태그의 의미는 list_pos_tags 도구로 받거나 품사 태그표에서 확인하세요. 사용자 사전 이름을 넘기는 custom_dict_names 는 사용자 사전으로 만든 사전을 함께 적용할 때 사용합니다.

참고용 리소스

도구(tool)와 별개로, MCP 리소스(resource) 로 참고 자료도 제공합니다. AI 도구가 MCP 리소스를 지원하면 URI 로 불러와 맥락에 활용할 수 있습니다.

리소스 URI	내용	인증
`bareun://pos-tags`	47개 품사 태그표(코드·이름·분류). `list_pos_tags` 도구와 동일 데이터	API 키
`bareun://server-info`	서버 메타데이터 — 이름·버전·빌드 종류·활성 도구/리소스 목록	API 키
`bareun://custom-dicts`	서버에 등록된 사용자 사전 도메인 이름 목록	유효한 API 키 필요

custom-dicts 는 유효한 API 키를 요구합니다

bareun://custom-dicts 는 서버 운영 정보(등록된 사용자 사전 목록)이므로, 키가 없거나 유효하지 않으면 거부됩니다. 여기서 받은 도메인 이름을 analyze_syntax·correct_grammar 의 custom_dict_names 에 넣어 함께 적용할 수 있습니다.

사용자 사전은 API 키(사용자)별로 분리되므로, 이 목록도 호출에 쓰인 키 기준입니다. 자세한 내용은 사용자 사전 — API 키별 분리를 참고하세요.

서버 버전·구성 확인하기

bareun://server-info 리소스를 읽으면 서버의 버전과 빌드 종류, 사용할 수 있는 도구·리소스 목록을 한 번에 받을 수 있습니다. 클라이언트가 연결 직후 "이 서버가 맞춤법 검사를 지원하는지", "어떤 도구가 있는지"를 파악할 때 유용합니다.

{
  "name": "bareun",
  "title": "바른 한국어 형태소 분석·맞춤법 검사",
  "version": "v3.0.0",
  "build": "revision",
  "tools": ["analyze_syntax", "tokenize", "list_pos_tags", "correct_grammar"],
  "resources": ["bareun://pos-tags", "bareun://server-info", "bareun://custom-dicts"]
}

version — 바른 빌드 버전(git describe 기준). 릴리스 태그면 v3.0.0, 태그 이후 커밋이 있으면 v3.0.0-12-g1a2b3c 처럼 표시됩니다.
build — revision(맞춤법 검사기 포함) 또는 standard. MCP 는 revision 빌드에서만 제공되므로, server-info 를 읽을 수 있다는 것 자체가 맞춤법 검사 지원 서버라는 뜻입니다.
tools/resources — 현재 활성화된 도구·리소스 목록(빌드 구성에 따라 자동으로 반영됩니다).

리소스를 지원하지 않는 클라이언트는 같은 정보를 직접 호출로 받을 수 있습니다 — resources/read 메서드에 {"uri": "bareun://server-info"} 를 넣어 호출하세요.

인증

바른 MCP 엔드포인트는 API 키로 보호됩니다. 모든 요청에 다음 중 한 가지 방식으로 키를 넣어 주세요.

api-key 헤더Authorization 헤더

api-key: 발급받은_API_키

Authorization: Bearer 발급받은_API_키

키가 없거나 권한이 없으면 요청이 거부됩니다. API 키 발급과 사용량은 클라우드에서 사용하기 안내를 참고하세요.

AI 도구에 등록하기

원격 MCP 서버로 등록하는 방법은 도구마다 조금씩 다르지만, 공통적으로 엔드포인트 주소와 API 키 헤더만 지정하면 됩니다. 엔드포인트는 https://<호스트>:<포트>/mcp 형태이며, 아래 예시의 https://api.bareun.ai:443 을 직접 설치한 서버 주소(예: http://localhost:5656)로 바꾸면 그대로 동작합니다. 발급받은_API_키 자리에는 실제 키를 넣으세요.

Claude CodeVS CodeCursorClaude Desktop

터미널에서 한 줄로 추가합니다.

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

추가 후 claude mcp list 로 연결 상태를, 대화 중 /mcp 로 도구 목록을 확인할 수 있습니다.

작업 영역에 .vscode/mcp.json 을 만들거나, 명령 팔레트에서 MCP: Add Server 를 실행합니다.

{
  "servers": {
    "bareun": {
      "type": "http",
      "url": "https://api.bareun.ai:443/mcp",
      "headers": { "api-key": "발급받은_API_키" }
    }
  }
}

채팅을 에이전트 모드로 두면 등록한 도구를 모델이 사용할 수 있습니다.

프로젝트의 .cursor/mcp.json(또는 전역 ~/.cursor/mcp.json)에 추가합니다.

{
  "mcpServers": {
    "bareun": {
      "url": "https://api.bareun.ai:443/mcp",
      "headers": { "api-key": "발급받은_API_키" }
    }
  }
}

Settings → MCP 화면에서 bareun 서버와 도구가 보이면 연결된 것입니다.

설정 → 개발자 → 설정 파일 편집(claude_desktop_config.json)에 추가합니다. Claude Desktop 은 헤더 인증이 필요한 원격 HTTP 서버를 mcp-remote 브리지로 연결합니다 (Node.js 필요).

{
  "mcpServers": {
    "bareun": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://api.bareun.ai:443/mcp",
        "--header", "api-key: 발급받은_API_키"
      ]
    }
  }
}

(일부 플랜에서는 설정 → 커넥터에서 URL 로 직접 추가하는 방법도 제공됩니다.)

등록 후 AI 도구를 다시 시작하면 analyze_syntax·tokenize·list_pos_tags·correct_grammar 가 사용 가능한 도구 목록에 나타납니다. 이제 에이전트에게 "이 문장을 바른으로 교정해 줘" 처럼 요청하면 됩니다.

연결이 잘 됐는지 확인하기

대부분의 MCP 도구에는 등록된 서버와 도구 목록을 보여주는 화면이 있습니다. 거기에 bareun 서버와 도구들이 보이면 정상 연결된 것입니다. 보이지 않으면 엔드포인트 주소 끝에 /mcp 가 붙었는지, API 키 헤더가 들어갔는지 확인하세요.

연결 테스트 (개발자용)

등록이 잘 됐는지 빠르게 확인하려면 공식 MCP Inspector 로 엔드포인트를 직접 확인할 수 있습니다(Node.js 필요).

npx @modelcontextprotocol/inspector

Inspector 화면에서 Transport 를 Streamable HTTP, URL 을 https://<호스트>:<포트>/mcp 로 두고, 헤더에 api-key: 발급받은_API_키 를 넣어 연결하면 도구·리소스 목록이 보이고 각 도구를 눌러 호출해 볼 수 있습니다.

MCP 는 JSON-RPC 2.0 위에서 동작하므로, curl 같은 일반 HTTP 도구로도 호출할 수 있습니다. 도구 호출 요청은 다음과 같은 모양입니다(이해를 돕기 위한 예시).

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "analyze_syntax",
    "arguments": { "text": "나는 학교에 간다.", "format": "compact" }
  }
}

직접 호출 시 순서

curl 로 직접 호출할 때는 먼저 initialize 로 세션을 시작하고, 응답 헤더의 Mcp-Session-Id 를 이후 요청에 함께 보내야 합니다. MCP Inspector 나 MCP 를 지원하는 AI 도구를 쓰면 이 절차가 자동으로 처리되므로 도구 호출만 신경 쓰면 됩니다.

자주 묻는 질문

Q. MCP 를 쓰려면 새 포트를 열거나 별도 프로그램을 설치해야 하나요?

아니요. 바른 서버가 이미 열려 있는 같은 주소의 /mcp 경로가 MCP 엔드포인트입니다. 추가 포트나 별도 설치 없이 바로 사용할 수 있습니다.

Q. 형태소 분석 전용 바른에서도 MCP 를 쓸 수 있나요?

아니요. MCP(/mcp 엔드포인트)는 맞춤법 검사기가 포함된 바른에서만 제공됩니다. 형태소 분석 전용 바른에는 /mcp 엔드포인트가 없습니다. 맞춤법 검사기가 포함된 바른에서는 analyze_syntax·tokenize·list_pos_tags·correct_grammar 네 도구가 모두 제공되며, 설치형 맞춤법 검사기에서도 동일하게 사용할 수 있습니다.

Q. 인증은 어떻게 하나요?

api-key 헤더에 발급받은 API 키를 넣거나, Authorization: Bearer <키> 형식으로 보냅니다. 둘 중 어느 방식이든 됩니다. 키가 없으면 요청이 거부됩니다.

Q. analyze_syntax 의 full 과 compact 는 무엇이 다른가요?

full 은 형태소·품사·위치까지 담은 전체 결과를, compact 는 표층형/품사 를 공백으로 이은 한 줄 요약을 돌려줍니다. 결과를 사람이 빠르게 읽거나 토큰을 아끼고 싶을 때는 compact 가 편리합니다.

Q. 품사 코드(NNG, JKS 등)의 뜻은 어떻게 알 수 있나요?

list_pos_tags 도구를 호출하면 47개 품사 태그의 코드·이름·분류를 한 번에 받을 수 있습니다. 같은 내용을 bareun://pos-tags 리소스로도 읽을 수 있어, AI 도구가 분석 결과를 해석할 때 참고 자료로 불러올 수 있습니다.

Q. 분석 결과의 위치 값이 기대와 다르게 나옵니다.

형태소의 위치 값은 encoding 옵션이 정한 단위로 셉니다. 기본값은 글자 수 기준인 utf32 입니다. 결과를 자바스크립트·자바에서 처리하면 utf16, Go·C++ 에서 처리하면 utf8 로 맞춰 호출하세요.

Q. 서버 버전이나 지원 도구를 어떻게 확인하나요?

bareun://server-info 리소스를 읽으면 서버 버전·빌드 종류와 활성 도구·리소스 목록을 한 번에 받을 수 있습니다. 리소스를 지원하지 않는 클라이언트는 resources/read 에 {"uri": "bareun://server-info"} 를 넣어 호출하면 됩니다.

도움이 되었나요?