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

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

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

두 가지 연동 방식

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

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

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

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

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

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

직접 에이전트나 앱을 만들 때는 바른을 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())

②-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)

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

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)

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" 메시지로 덧붙여 한 번 더 호출합니다.

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 로 회신

②-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 라이브러리를 제공합니다(자세히는 개발하기 개요 참고).

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에 정리되어 있습니다.

어떤 방법을 고를까

자주 묻는 질문

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

챗GPT는 됩니다. 설정에서 개발자 모드를 켜면 사용자 지정 커넥터로 바른 MCP 주소를 직접 추가할 수 있습니다(등록 가이드). 제미나이 웹 채팅창은 아직 임의의 MCP 서버 주소를 입력하는 설정이 없습니다. 그럴 때는 코드로 직접 연동(방식 ②)하거나, MCP 를 지원하는 도구(Claude·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개 품사 태그를 사용합니다.