개요

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

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

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

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

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

api-key 헤더에 발급받은 API 키를 넣거나, Authorization: Bearer 형식으로 보냅니다. 둘 중 어느 방식이든 사용할 수 있으며, 키가 없으면 요청이 거부됩니다. VS Code 처럼 OAuth 로그인을 지원하는 도구는 헤더 없이 연결한 뒤 브라우저 로그인 창에 바른 API 키를 입력하면 됩니다.

Q: VS Code 에서 바른 MCP 의 Sign in 을 누르면 무엇을 입력하나요?

OAuth 로그인을 지원하는 도구는 처음 연결할 때 브라우저 로그인 창을 엽니다. 거기에 바른 API 키를 입력하면 됩니다. 바른은 API 키로 사용자를 식별하므로 로그인 창에서 입력하는 값이 곧 API 키이며, 한 번 로그인하면 도구가 인증 정보를 보관합니다.

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 키가 없으면 요청이 거부됩니다. API 키 발급과 사용량은 클라우드에서 사용하기 안내를 참고하세요.

OAuth 로그인(Sign in)도 지원합니다

VS Code 처럼 OAuth 로그인을 쓰는 도구는 헤더를 직접 넣지 않아도 됩니다. 서버에 처음 연결할 때 브라우저 로그인 창이 열리고, 거기에 바른 API 키를 입력하면 연결됩니다. 바른은 API 키로 사용자를 식별하므로, 로그인 창에서 입력하는 값이 곧 API 키입니다. 한 번 로그인하면 도구가 인증 정보를 안전하게 보관해 다음부터는 다시 입력하지 않아도 되고, API 키가 설정 파일에 남지 않는 장점이 있습니다.

AI 도구에 등록하기

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

환경별 상세 가이드

아래는 빠른 등록을 위한 요약입니다. 각 환경의 단계별 안내·OAuth 로그인·문제 해결은 환경별 가이드를 참고하세요 — Claude Code · Claude Desktop · VS Code · Cursor · Codex CLI · 그 밖의 클라이언트.

Claude CodeVS CodeCursorClaude DesktopCodex CLI

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

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_키" }
    }
  }
}

채팅을 에이전트 모드로 두면 등록한 도구를 모델이 사용할 수 있습니다. headers 를 빼고 url 만 두면 VS Code 가 처음 연결 시 브라우저 로그인 창을 열어 OAuth 로그인을 진행합니다 (자세히는 VS Code 가이드 참고).

프로젝트의 .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 로 직접 추가하는 방법도 제공됩니다.)

~/.codex/config.toml 에 [mcp_servers.bareun] 표를 추가하고 url 을 지정합니다. API 키는 환경변수 토큰으로 두는 방식을 권장합니다.

[mcp_servers.bareun]
url = "https://api.bareun.ai:443/mcp"
bearer_token_env_var = "BAREUN_API_KEY"

실행 전 export BAREUN_API_KEY="발급받은_API_키" 로 키를 설정하세요. 정적 헤더 (http_headers = { "api-key" = "..." })나 mcp-remote 브리지로도 등록할 수 있습니다 (자세히는 Codex CLI 가이드 참고).

등록 후 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 <키> 형식으로 보냅니다. 둘 중 어느 방식이든 됩니다. 키가 없으면 요청이 거부됩니다.

OAuth 로그인을 지원하는 도구(VS Code 등)는 처음 연결할 때 브라우저 로그인 창을 엽니다. 거기에 바른 API 키를 입력하면 됩니다. 바른은 API 키로 사용자를 식별하므로 로그인 창에서 입력하는 값이 곧 API 키이며, 한 번 로그인하면 도구가 인증 정보를 보관합니다. 환경별 로그인 절차는 환경별 등록 가이드를 참고하세요.

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"} 를 넣어 호출하면 됩니다.

도움이 되었나요?

개요