연동 방법 한눈에

Q: 바른을 AI 에 연결하는 방법에는 무엇이 있나요?

크게 두 가지입니다. 코딩 없이 MCP 로 자동 연결하는 방식(Claude, Cursor, VS Code 등)과, 내 코드에서 바른을 도구·함수로 연동하는 방식입니다. 후자는 코드에서 MCP 서버에 직접 연결하거나, 바른 API 를 호출하는 함수를 만들어 AI SDK(Gemini, OpenAI, Claude 등)에 도구로 등록하는 방법으로 나뉩니다.

Q: 바른 맞춤법 검사 API 의 교정된 문장은 어느 필드에 들어 있나요?

맞춤법 검사 API(CorrectError)의 응답에서 교정된 전체 문장은 revised 필드에 담깁니다. 교정 구간별 원문과 교정문은 revised_blocks 로 함께 제공됩니다.

Q: 바른 API 인증은 어떻게 하나요?

요청 헤더에 api-key 로 API 키를 넣거나, Authorization: Bearer 형식으로 보냅니다. MCP 엔드포인트(/mcp)도 같은 두 방식을 모두 받습니다.

Q: 맞춤법 검사도 설치형으로 쓸 수 있나요?

맞춤법 검사기는 기본적으로 클라우드(api.bareun.ai)로 제공됩니다. 형태소 분석은 클라우드와 설치형 모두 사용할 수 있습니다. 설치형 서버를 쓰면 예시의 주소를 그 서버 주소(예: http://localhost:5656)로 바꾸면 됩니다.

AI·에이전트에서 바른 활용하기

대형 언어모델(Claude·Gemini·GPT 등)은 글을 자연스럽게 쓰지만, 한국어 특유의 띄어쓰기, 조사 선택, 미묘한 어법에서는 어긋날 때가 많습니다. 이럴 때 바른을 AI 옆에 붙여 두면, AI 가 글을 쓰거나 분석하는 도중에 스스로 바른을 호출해 형태소 분석과 맞춤법 검사를 수행하고, 그 결과를 받아 더 정확한 한국어 결과를 만들 수 있습니다.

핵심 한 줄

바른을 AI 에 연결하는 길은 크게 두 가지입니다. ① 코딩 없이 MCP 로 자동 연결하거나, ② 내 코드에서 바른을 도구·함수로 연동하는 것입니다. 사용하는 도구가 MCP 를 지원하면 ①, 직접 에이전트를 만든다면 ②를 고르세요.

이 문서는 두 방식을 한눈에 정리합니다. 환경별 상세 설정은 각 항목에서 연결하는 문서를 참고하세요.

두 가지 연동 방식

구분	① MCP 로 자동 연결	② 프로그래밍으로 연동
누구에게	Claude·Cursor·VS Code 등 완성된 AI 도구 사용자	직접 에이전트·앱을 만드는 개발자
코딩	필요 없음(설정 파일/메뉴)	필요(파이썬·자바스크립트 등)
연결 대상	바른 서버의 `/mcp` 엔드포인트	바른 API(Connect/gRPC/REST) 또는 `/mcp`
AI 가 도구를 고르는 방식	AI 도구가 알아서 호출	내가 SDK 에 도구로 등록 → 모델이 호출
대표 사례	"이 문장 바른으로 고쳐줘"라고 채팅	글쓰기 파이프라인에 교정 단계 삽입

flowchart TD
    A["바른을 AI 에 연결하고 싶다"] --> B{"내가 코드를 짜는가?"}
    B -->|"아니오 — 완성된 AI 도구를 쓴다"| C{"그 도구가 MCP 를 지원하는가?"}
    B -->|"예 — 에이전트·앱을 만든다"| D["② 프로그래밍 연동"]
    C -->|"예 (Claude·Cursor·VS Code 등)"| E["① MCP 로 자동 연결"]
    C -->|"아니오 (제미나이·챗GPT 웹 채팅 등)"| D

방식 ① — MCP 서버로 자동 연결(코딩 없이)

MCP(Model Context Protocol) 는 AI 도구가 외부 기능을 표준 방식으로 불러 쓰도록 약속한 규격입니다. 맞춤법 검사기가 포함된 바른은 서버가 열리는 같은 주소의 /mcp 경로에서 MCP 서버로 동작하므로, 별도 포트나 설치 없이 바로 연결할 수 있습니다.

바른 MCP 서버는 다음 네 가지 도구를 제공합니다.

도구 이름	하는 일
`analyze_syntax`	문장을 어절·형태소로 나누고 품사를 붙입니다(형태소 분석).
`tokenize`	문장을 어절(토큰) 단위로 나눕니다.
`correct_grammar`	맞춤법·띄어쓰기를 교정합니다.
`list_pos_tags`	바른이 쓰는 47개 품사 태그 목록을 돌려줍니다.

연결은 엔드포인트 주소(https://api.bareun.ai:443/mcp, 설치형은 http://localhost:5656/mcp)와 API 키만 지정하면 끝입니다. 도구를 등록한 뒤 "이 문장을 바른으로 교정해 줘"처럼 평소대로 말을 걸면, AI 가 알아서 바른을 호출합니다.

환경별 등록 방법은 별도 문서에서

각 도구의 단계별 설정·OAuth 로그인·문제 해결은 환경별 가이드를 참고하세요 — 개요 · Claude Code · Claude Desktop · VS Code · Cursor · Codex CLI · 그 밖의 클라이언트.

제미나이·챗GPT 같은 웹 채팅창에서는 직접 추가할 수 없습니다

구글 제미나이나 챗GPT 의 웹 채팅창은 사용자가 임의의 MCP 서버 주소를 입력하는 설정을 열어 두지 않았습니다. 따라서 그 화면에서는 바른 MCP 를 바로 붙일 수 없습니다. 이런 환경에서 바른을 쓰려면 아래 방식 ②(프로그래밍 연동) 로 직접 코드에 연결하거나, MCP 를 지원하는 도구(Claude Desktop·Cursor·VS Code 등)를 사용하세요.

방식 ② — 내 코드에서 도구·함수로 연동

직접 에이전트나 앱을 만들 때는 바른을 AI 모델의 도구(tool)·함수(function) 로 쥐여 줍니다. 그러면 모델이 답을 만들다가 한국어 교정·분석이 필요할 때 스스로 바른을 호출해 결과를 받은 뒤, 그 결과를 반영해 최종 답을 완성합니다. 두 갈래가 있습니다.

②-A. 코드에서 MCP 서버에 직접 연결 — 바른 MCP 의 네 도구를 한 번에 모델에 붙입니다.
②-B. 함수 호출(function/tool calling)로 바른 API 연결 — 바른 API 를 호출하는 함수를 하나 만들어 모델 도구로 등록합니다.

준비물은 바른 API 키(bareun.ai/api-key에서 발급, 클라우드에서 사용하기 참고)와 연동할 AI SDK 의 API 키입니다.

②-A. 코드에서 MCP 서버에 직접 연결

MCP 서버 연결을 지원하는 SDK 라면, 바른 /mcp 엔드포인트를 통째로 도구로 붙일 수 있습니다. 형태소 분석·교정 등 네 도구를 모델이 알아서 골라 쓰므로 가장 유연합니다.

아래는 구글 google-genai SDK 와 fastmcp 클라이언트로 제미나이에 바른 MCP 를 붙이는 예시입니다. 바른은 인증에 api-key 헤더와 Authorization: Bearer <키>를 모두 받으므로, fastmcp 의 BearerAuth 에 바른 API 키를 그대로 넣으면 됩니다.

import asyncio
from google import genai
from fastmcp import Client
from fastmcp.client.auth import BearerAuth

# 1) 바른 MCP 서버 연결 — API 키를 Bearer 토큰으로 사용
bareun_mcp = Client(
    "https://api.bareun.ai:443/mcp",
    auth=BearerAuth("발급받은_바른_API_키"),
)
# 2) 제미나이 클라이언트 (구글 AI 스튜디오 API 키)
gemini = genai.Client(api_key="구글_AI_스튜디오_API_키")

async def main():
    async with bareun_mcp as session:
        resp = gemini.models.generate_content(
            model="gemini-2.5-flash",  # 원하는 제미나이 모델
            contents="다음 문장의 맞춤법과 띄어쓰기를 바른으로 교정해줘:\n'원하는제품을 빨리찻고싶어요.'",
            config={"tools": [session]},  # 바른 MCP 세션을 도구로 통째로 주입
        )
        print(resp.text)

asyncio.run(main())

다른 SDK 에서도 가능합니다

OpenAI Agents SDK, Anthropic Claude API 등 여러 SDK 가 원격 MCP 서버 연결을 지원합니다. 연결 방식(메서드명·옵션)은 SDK 마다 다르고 자주 갱신되므로, 정확한 사용법은 각 SDK 의 공식 문서를 확인하세요. 어느 경우든 바른 쪽에 넘기는 값은 엔드포인트 주소 + API 키로 동일합니다.

②-B. 함수 호출로 바른 API 연결

MCP 연결을 쓰지 않아도, 바른 API 를 호출하는 함수를 하나 만들어 모델에 도구로 등록하면 같은 효과를 얻습니다. 의존성이 적고 어떤 SDK 와도 잘 맞습니다.

먼저 바른 맞춤법 검사 API 를 호출하는 함수를 만듭니다. 바른의 모든 API 는 하나의 포트에서 gRPC·REST 를 함께 처리하며(자세히는 맞춤법 검사 API·REST API 참고), 맞춤법 검사는 POST /bareun.RevisionService/CorrectError 로 호출합니다. 교정된 문장은 응답의 revised 필드에 담겨 옵니다.

import requests

# 교정은 클라우드(맞춤법 검사기)에서 제공됩니다. 설치형이면 http://localhost:5656 로 바꾸세요.
BAREUN_CORRECT_URL = "https://api.bareun.ai:443/bareun.RevisionService/CorrectError"
BAREUN_API_KEY = "발급받은_바른_API_키"

def correct_korean(text: str) -> str:
    """입력한 한국어 문장의 맞춤법·띄어쓰기를 바른으로 교정해 교정문을 돌려준다."""
    resp = requests.post(
        BAREUN_CORRECT_URL,
        headers={"api-key": BAREUN_API_KEY, "Content-Type": "application/json"},
        json={"document": {"content": text}},
    )
    resp.raise_for_status()
    # 교정된 전체 문장은 "revised" 필드에 들어 있다.
    return resp.json().get("revised", text)

형태소 분석도 같은 방식입니다

형태소 분석이 필요하면 POST /bareun.LanguageService/AnalyzeSyntax 에 같은 형태로 ({"document": {"content": "..."}}) 호출하면 됩니다. 응답에는 어절·형태소·품사가 담깁니다. 자세한 형식은 형태소 분석 API를 참고하세요.

이제 이 함수를 각 AI SDK 에 도구로 등록합니다.

제미나이(Gemini)OpenAI(GPT)Claude

제미나이는 파이썬 함수를 그대로 도구로 받아, 함수 이름·독스트링·타입힌트에서 도구 설명을 자동으로 만들어 줍니다.

from google import genai

client = genai.Client(api_key="구글_AI_스튜디오_API_키")

resp = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="다음 문장을 바른으로 교정하고 이유도 설명해줘: '원하는제품을 빨리찻고싶어요.'",
    config={"tools": [correct_korean]},  # 위에서 만든 함수를 그대로 도구로 등록
)
print(resp.text)

OpenAI 는 도구 스키마를 JSON 으로 명시하고, 모델이 도구 호출을 요청하면 함수를 실행해 결과를 다시 전달합니다.

from openai import OpenAI

client = OpenAI(api_key="OpenAI_API_키")

tools = [{
    "type": "function",
    "function": {
        "name": "correct_korean",
        "description": "한국어 문장의 맞춤법·띄어쓰기를 바른으로 교정한다.",
        "parameters": {
            "type": "object",
            "properties": {"text": {"type": "string", "description": "교정할 한국어 문장"}},
            "required": ["text"],
        },
    },
}]

messages = [{"role": "user", "content": "이 문장 교정해줘: '원하는제품을 빨리찻고싶어요.'"}]
resp = client.chat.completions.create(model="gpt-4o", messages=messages, tools=tools)
# 모델이 tool_calls 를 요청하면 correct_korean() 을 실행한 뒤
# 결과를 role="tool" 메시지로 덧붙여 한 번 더 호출합니다.

Claude(Anthropic)도 도구 스키마를 명시하고, 응답의 tool_use 블록을 받아 함수를 실행한 뒤 tool_result 로 회신하는 흐름입니다.

import anthropic

client = anthropic.Anthropic()  # ANTHROPIC_API_KEY 환경변수 사용

tools = [{
    "name": "correct_korean",
    "description": "한국어 문장의 맞춤법·띄어쓰기를 바른으로 교정한다.",
    "input_schema": {
        "type": "object",
        "properties": {"text": {"type": "string", "description": "교정할 한국어 문장"}},
        "required": ["text"],
    },
}]

messages = [{"role": "user", "content": "이 문장 교정해줘: '원하는제품을 빨리찻고싶어요.'"}]
resp = client.messages.create(
    model="claude-opus-4-8", max_tokens=1024, tools=tools, messages=messages,
)
# resp.content 의 tool_use 블록을 찾아 correct_korean() 실행 → tool_result 로 회신

SDK 의 정확한 사용법은 공식 문서로

위 예시는 흐름을 보여 주기 위한 것이며, 각 SDK 의 도구 등록 방식·모델 이름·도구 호출 루프 처리 방법은 버전에 따라 달라집니다. 실제 구현은 사용하는 SDK 의 function/tool calling 공식 문서를 확인하세요. 바른 쪽 호출(엔드포인트·헤더·revised 필드)은 동일합니다.

②-C. LangChain 등 에이전트 프레임워크

LangChain·LlamaIndex 같은 에이전트 프레임워크에서도 위 correct_korean 함수를 그대로 도구로 감싸면 됩니다. 예를 들어 LangChain 에서는 @tool 데코레이터 한 줄로 등록합니다.

from langchain_core.tools import tool

@tool
def correct_korean(text: str) -> str:
    """한국어 문장의 맞춤법·띄어쓰기를 바른으로 교정한다."""
    resp = requests.post(
        BAREUN_CORRECT_URL,
        headers={"api-key": BAREUN_API_KEY, "Content-Type": "application/json"},
        json={"document": {"content": text}},
    )
    resp.raise_for_status()
    return resp.json().get("revised", text)

# 이 도구를 에이전트의 tools 목록에 넣으면, 모델이 필요할 때 호출합니다.

②-D. 클라이언트 라이브러리·직접 API 호출

에이전트가 아니라 일반 코드에서 바른을 쓸 때는 공식 클라이언트 라이브러리가 가장 편합니다. 바른은 파이썬·자바·자바스크립트·R 라이브러리를 제공합니다(자세히는 개발하기 개요 참고).

파이썬자바스크립트자바R

pip install bareunpy

npm install bareun

<dependency>
  <groupId>ai.bareun.tagger</groupId>
  <artifactId>bareun</artifactId>
</dependency>

install.packages("RBareun")

라이브러리 없이 직접 호출하려면, 위 correct_korean 함수처럼 Connect/REST 엔드포인트에 POST 하면 됩니다. 전체 API 목록과 형식은 REST API·맞춤법 검사 API·형태소 분석 API에 정리되어 있습니다.

어떤 방법을 고를까

상황	추천 방법
Claude·Cursor·VS Code 등 MCP 지원 도구를 그냥 쓰고 싶다	① MCP 자동 연결
제미나이·챗GPT 웹 채팅에서 쓰고 싶다	직접은 불가 → ② 프로그래밍 연동 또는 MCP 지원 도구
에이전트를 만드는데 분석·교정 도구를 한 번에 붙이고 싶다	②-A 코드에서 MCP 직접 연결
특정 SDK 에서 교정 한 가지만 깔끔히 붙이고 싶다	②-B 함수 호출
LangChain 등 프레임워크의 도구로 쓰고 싶다	②-C 프레임워크 도구
에이전트가 아니라 일반 코드에서 호출한다	②-D 클라이언트 라이브러리

자주 묻는 질문

Q. 제미나이나 챗GPT 웹 채팅창에 바른 MCP 를 바로 추가할 수 있나요?

아니요. 두 서비스의 웹 채팅창은 사용자가 임의의 MCP 서버 주소를 입력하는 설정을 열어 두지 않았습니다. 바른을 쓰려면 코드로 직접 연동(방식 ②)하거나, MCP 를 지원하는 도구(Claude Desktop·Cursor·VS Code 등)에서 바른 MCP 를 등록해 사용하세요.

Q. MCP 직접 연결과 함수 호출 중 무엇이 더 좋나요?

MCP 직접 연결(②-A)은 형태소 분석·교정 등 네 도구를 한 번에 붙여 모델이 알아서 고르게 하므로 에이전트에 적합합니다. 함수 호출(②-B)은 필요한 기능 하나만 깔끔히 붙일 때, 또는 MCP 연결을 지원하지 않는 SDK 에서 편리합니다.

Q. 교정된 문장은 응답의 어느 필드에 들어 있나요?

맞춤법 검사 API(CorrectError)의 응답에서 교정된 전체 문장은 revised 필드에 담깁니다. 원문은 revised_blocks(교정 구간별 원문/교정문)와 함께 제공됩니다. 자세한 응답 구조는 맞춤법 검사 API를 참고하세요.

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

요청 헤더에 api-key: 발급받은_API_키 를 넣거나, Authorization: Bearer 발급받은_API_키 형식으로 보냅니다. MCP 엔드포인트(/mcp)도 같은 두 방식을 모두 받습니다. API 키 발급은 클라우드에서 사용하기를 참고하세요.

Q. 맞춤법 검사도 설치형으로 쓸 수 있나요?

맞춤법 검사기는 기본적으로 클라우드(api.bareun.ai)로 제공됩니다. 형태소 분석은 클라우드와 설치형 모두 사용할 수 있습니다. 설치형 서버를 쓰는 경우 위 예시의 주소를 그 서버 주소(예: http://localhost:5656)로 바꾸면 됩니다.

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

형태소 분석 결과의 품사 코드는 품사 태그표에서 확인하거나, MCP 의 list_pos_tags 도구로 받을 수 있습니다. 바른은 국립국어원 기준 47개 품사 태그를 사용합니다.

도움이 되었나요?