Using Bareun from AI and agents

Large language models (Claude, Gemini, GPT, and others) write fluently, but they often slip on Korean-specific word spacing, particle choice, and subtle grammar. If you put Bareun next to the AI, then while the AI is writing or analyzing text it can call Bareun by itself to run morphological analysis and spell checking, and use the results to produce more accurate Korean.

This document summarizes both approaches at a glance. For detailed setup in each environment, see the documents linked in each section.

Two ways to integrate

flowchart TD
    A["I want to connect Bareun to an AI"] --> B{"Am I writing code?"}
    B -->|"No: I use a finished AI tool"| C{"Does that tool support MCP?"}
    B -->|"Yes: I build agents or apps"| D["② Integrate with code"]
    C -->|"Yes (Claude, ChatGPT, Cursor, VS Code, etc.)"| E["① Connect automatically through MCP"]
    C -->|"No (Gemini web chat, etc.)"| D

Approach ①: Connect automatically through the MCP server (no coding)

MCP (Model Context Protocol) is a standard that lets AI tools call external features in a uniform way. Bareun, which includes the spell checker, runs as an MCP server on the /mcp path of the same address where the server opens, so you can connect right away with no extra port or installation.

The Bareun MCP server provides the following four tools.

To connect, you only need to specify the endpoint address (https://api.bareun.ai:443/mcp, or http://localhost:5656/mcp for an on-premises install) and an API key. After registering the tools, talk to the AI as usual, for example "Correct this sentence with Bareun," and the AI calls Bareun on its own.

Approach ②: Integrate as a tool or function in your code

When you build your own agent or app, you hand Bareun to the AI model as a tool or function. Then, when the model is composing an answer and needs Korean correction or analysis, it calls Bareun by itself, receives the result, and reflects it in the final answer. There are two branches.

• ②-A. Connect to the MCP server directly from code: attach all four tools of the Bareun MCP to the model at once.
• ②-B. Connect the Bareun API through function (tool) calling: write one function that calls the Bareun API and register it as a model tool.

You need a Bareun API key (issue one at bareun.ai/api-key; see Using it in the cloud) and the API key of the AI SDK you integrate with.

②-A. Connect to the MCP server directly from code

If your SDK supports connecting to MCP servers, you can attach the whole Bareun /mcp endpoint as tools. The model chooses among the four tools, including morphological analysis and correction, so this is the most flexible option.

Below is an example that attaches the Bareun MCP to Gemini with Google's google-genai SDK and the fastmcp client. Bareun accepts both the api-key header and Authorization: Bearer <key> for authentication, so you can pass your Bareun API key straight into fastmcp's BearerAuth.

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

# 1) Connect to the Bareun MCP server, using the API key as a Bearer token
bareun_mcp = Client(
    "https://api.bareun.ai:443/mcp",
    auth=BearerAuth("YOUR_BAREUN_API_KEY"),
)
# 2) Gemini client (Google AI Studio API key)
gemini = genai.Client(api_key="YOUR_GOOGLE_AI_STUDIO_API_KEY")

async def main():
    async with bareun_mcp as session:
        resp = gemini.models.generate_content(
            model="gemini-2.5-flash",  # the Gemini model you want
            contents="Correct the spelling and word spacing of the following sentence with Bareun:\n'원하는제품을 빨리찻고싶어요.'",
            config={"tools": [session]},  # inject the Bareun MCP session as tools, as a whole
        )
        print(resp.text)

asyncio.run(main())

②-B. Connect the Bareun API through function calling

Even without an MCP connection, you get the same effect by writing a function that calls the Bareun API and registering it with the model as a tool. It has few dependencies and works well with any SDK.

First, write a function that calls the Bareun spell check API. All Bareun APIs handle gRPC and REST on a single port (see Spell check API and REST API for details), and you call the spell check with POST /bareun.RevisionService/CorrectError. The corrected sentence comes back in the revised field of the response.

import requests

# Correction is provided by the cloud (spell checker). For an on-premises install, change this to http://localhost:5656.
BAREUN_CORRECT_URL = "https://api.bareun.ai:443/bareun.RevisionService/CorrectError"
BAREUN_API_KEY = "YOUR_BAREUN_API_KEY"

def correct_korean(text: str) -> str:
    """Correct the spelling and word spacing of the given Korean sentence with Bareun and return the corrected text."""
    resp = requests.post(
        BAREUN_CORRECT_URL,
        headers={"api-key": BAREUN_API_KEY, "Content-Type": "application/json"},
        json={"document": {"content": text}},
    )
    resp.raise_for_status()
    # The full corrected sentence is in the "revised" field.
    return resp.json().get("revised", text)

Now register this function as a tool in each AI SDK.

from google import genai

client = genai.Client(api_key="YOUR_GOOGLE_AI_STUDIO_API_KEY")

resp = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Correct the following sentence with Bareun and explain the reasons too: '원하는제품을 빨리찻고싶어요.'",
    config={"tools": [correct_korean]},  # register the function defined above as a tool, as is
)
print(resp.text)

from openai import OpenAI

client = OpenAI(api_key="YOUR_OPENAI_API_KEY")

tools = [{
    "type": "function",
    "function": {
        "name": "correct_korean",
        "description": "Correct the spelling and word spacing of a Korean sentence with Bareun.",
        "parameters": {
            "type": "object",
            "properties": {"text": {"type": "string", "description": "The Korean sentence to correct"}},
            "required": ["text"],
        },
    },
}]

messages = [{"role": "user", "content": "Correct this sentence: '원하는제품을 빨리찻고싶어요.'"}]
resp = client.chat.completions.create(model="gpt-4o", messages=messages, tools=tools)
# If the model requests tool_calls, run correct_korean(),
# append the result as a role="tool" message, and call the model once more.

import anthropic

client = anthropic.Anthropic()  # uses the ANTHROPIC_API_KEY environment variable

tools = [{
    "name": "correct_korean",
    "description": "Correct the spelling and word spacing of a Korean sentence with Bareun.",
    "input_schema": {
        "type": "object",
        "properties": {"text": {"type": "string", "description": "The Korean sentence to correct"}},
        "required": ["text"],
    },
}]

messages = [{"role": "user", "content": "Correct this sentence: '원하는제품을 빨리찻고싶어요.'"}]
resp = client.messages.create(
    model="claude-opus-4-8", max_tokens=1024, tools=tools, messages=messages,
)
# Find the tool_use block in resp.content → run correct_korean() → reply with a tool_result

②-C. Agent frameworks such as LangChain

In agent frameworks such as LangChain and LlamaIndex, you can wrap the correct_korean function above as a tool, as it is. For example, in LangChain you register it with a single @tool decorator line.

from langchain_core.tools import tool

@tool
def correct_korean(text: str) -> str:
    """Correct the spelling and word spacing of a Korean sentence with Bareun."""
    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)

# Put this tool in the agent's tools list, and the model calls it when needed.

②-D. Client libraries and direct API calls

When you use Bareun in ordinary code rather than in an agent, the official client libraries are the most convenient. Bareun provides libraries for Python, Java, JavaScript, and R (see Development overview for details).

pip install bareunpy

npm install bareun

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

install.packages("RBareun")

To call without a library, POST to the Connect/REST endpoint, as in the correct_korean function above. The full API list and formats are in REST API, Spell check API, and Morphological analysis API.

Which approach to choose

Frequently asked questions

Q. Can I add the Bareun MCP directly to the Gemini or ChatGPT web chat window?

For ChatGPT, yes. If you turn on developer mode in settings, you can add the Bareun MCP address directly as a custom connector (registration guide). The Gemini web chat window does not yet have a setting for entering an arbitrary MCP server address. In that case, integrate directly in code (approach ②), or register the Bareun MCP in a tool that supports MCP (Claude, Cursor, VS Code, and others).

Q. Which is better, connecting MCP directly or function calling?

Connecting MCP directly (②-A) attaches all four tools at once, including morphological analysis and correction, and lets the model choose, so it suits agents. Function calling (②-B) is convenient when you want to attach just one feature cleanly, or when the SDK does not support MCP connections.

Q. Which field of the response holds the corrected sentence?

In the response of the spell check API (CorrectError), the full corrected sentence is in the revised field. The original text is provided together with revised_blocks (original and corrected text for each corrected segment). For the detailed response structure, see Spell check API.

Q. How does authentication to the Bareun API work?

Put api-key: YOUR_ISSUED_API_KEY in the request header, or send it as Authorization: Bearer YOUR_ISSUED_API_KEY. The MCP endpoint (/mcp) accepts both methods as well. To get an API key, see Using it in the cloud.

Q. Can I use the spell checker on-premises too?

The spell checker is provided mainly through the cloud (api.bareun.ai). Morphological analysis is available in both the cloud and on-premises installs. If you use an on-premises server, change the address in the examples above to that server's address (for example, http://localhost:5656).

Q. How do I find out what a POS code (NNG, JKS, and so on) means?

You can look up the POS codes in the morphological analysis results in the POS tag table, or get them with the MCP list_pos_tags tool. Bareun uses the 47 POS tags defined by the National Institute of Korean Language (NIKL).