Add Korean-language ability to AI agents with the Bareun MCP server

Bareun also runs as an MCP (Model Context Protocol) server. MCP is a standard that lets AI tools such as Claude and Cursor call external capabilities in a uniform way. When you connect Bareun as an MCP server, an AI agent can call Bareun on its own while writing or analyzing text, and perform Korean morphological analysis and spell checks.

Why MCP?

Large language models sometimes miss subtle word spacing and grammar in Korean sentences. If you attach Bareun as an MCP tool, the agent can hand analysis and correction to Bareun whenever it needs to, take the result, and produce more accurate Korean output.

You do not need a separate port or any extra installation. The /mcp path on the same address where the Bareun server listens is the MCP endpoint.

MCP is provided by Bareun builds that include the Korean spell checker

The MCP feature (the /mcp endpoint) is provided only by Bareun builds that include the Korean spell checker. A Bareun build for morphological analysis only has no /mcp endpoint. You can use MCP in the same way with the on-premises (self-hosted) Korean spell checker.

Tools provided

The MCP server of a Bareun build that includes the Korean spell checker provides the following tools.

Tool name	What it does	Main inputs
`analyze_syntax`	Splits a sentence into eojeol (space-delimited word units) and morphemes and attaches POS tags (morphological analysis).	`text` (required), `auto_split_sentence`, `auto_spacing`, `auto_jointing`, `custom_dict_names`, `encoding`, `format`, `with_sense`
`analyze_syntax_raw`	Returns the model output as is, without post-processing (compound noun and verb decomposition, automatic word spacing and joining, custom dictionary).	`text` (required), `auto_split_sentence`, `encoding`, `format`, `with_sense`
`tokenize`	Splits a sentence into eojeol (token) units.	`text` (required), `auto_spacing`, `encoding`
`correct_grammar`	Corrects spelling and word spacing.	`text` (required), `custom_dict_names`, correction options (below)
`search_dict`	Searches the Urimalsaem (Open Korean Dictionary) by jamo (initial, medial, final) conditions.	`pattern` (required), `anchor`, `pos`, `std_only`, `with_definition`, `limit`, `count_only`
`list_pos_tags`	Returns the list of the 47 POS tags Bareun uses (code, name, category).	(no input)

format option (analyze_syntax)

full (default): returns the full result, including morphemes, POS, and positions.
compact: returns a one-line summary in the form surface/POS surface/POS …. Example: 나는 → 나/NP 는/JX

with_sense option: homonym sense disambiguation (beta)

Whether 다리 is a bridge (橋) to cross or a leg (脚) of the body is not decided by the POS (NNG). If you set with_sense to true, each morpheme carries its sense number (dictionary sense number) and definition, which can help the agent avoid misunderstanding a word's meaning.

{ "name": "analyze_syntax",
  "arguments": { "text": "다리를 건넜다.", "with_sense": true } }

With format=full (default), each morpheme carries sense (sense number, definition, Urimalsaem number, selection probability). Morphemes without meaning (particles, endings, and so on) have no such key at all.
With format=compact, the sense number is attached to the one-line summary, as in 다리__005/NNG.
The default is false. If you do not turn it on, results and cost are the same as before.

This is a beta feature available since Bareun 3.1.0. For accuracy and limitations, see the Homonym sense disambiguation API.

encoding option (basis for position values)

The analysis result contains the position where each morpheme starts in the original text. encoding sets the unit in which this position is counted. Match it to the language of the side that processes the result.

utf32 (default): counts characters (code points). Fits Python strings well.
utf16: fits JavaScript and Java strings well.
utf8: counts bytes. Fits Go and C++ well.

search_dict: does what an AI cannot do by itself

Given a request such as "List all verbs that end in a ㅎ final consonant", an AI language model tends to recall a few and then make up plausible-sounding words. Both handling characters at the jamo level and scanning an entire dictionary without gaps are things language models are bad at. search_dict turns this request into a search over the whole Urimalsaem (about 1.13 million entries) and returns only entries that actually exist in the dictionary.

{ "name": "search_dict",
  "arguments": { "pattern": "*{//ㅎ}다", "pos": ["동사류"], "std_only": true } }

For the pattern syntax and search options, see the Urimalsaem phoneme search API. For concrete ways to use it from an agent (prompt examples), see Using phoneme search.

Correction options (correct_grammar)

Correction works with the defaults alone (all off). You can turn the options below on or off as needed, and all are specified as true/false (boolean). For example, when you correct an article headline, turn on treat_as_title.

Option	Default	What happens when on
`treat_as_title`	off	Treats the input as an article or text title when correcting it. Titles follow different rules from body text, for example they have no sentence-final ending or period, so turning this on gives more natural results when correcting titles.
`disable_split_sentence`	off	Does not split sentences. Normally the input is split into sentences and corrected; turn this on when the input is already a single sentence or you do not want line breaks treated as sentence boundaries.
`disable_caret_spacing`	off	Turns off compound noun splitting (word spacing) correction. Keeps closed-up compound nouns from being split apart.
`disable_vx_spacing`	off	Turns off auxiliary verb spacing correction. Does not apply corrections that join auxiliary verbs, such as '도와 주다 → 도와주다'.
`enable_limited_punctuation`	off	Applies the limited punctuation rules. Corrects with a narrower range of allowed punctuation marks.
`disable_confusion`	off	Turns off the confusable words model. Does not call the feature that uses context to fix easily confused words such as '되/돼' and '맞히다/맞추다' (faster, but confusable word correction is skipped).
`enable_cleanup_whitespace`	off	Cleans up unnecessary whitespace (removes repeated spaces, and so on).
`disable_typo_correction`	off	Turns off typo correction. Use this when you want only other corrections, such as word spacing, without spelling error correction.
`enable_sentence_check`	off	Enables sentence-level checks. Looks beyond the eojeol level at things like agreement across the whole sentence.
`enable_public_term_refine`	off	Turns on public-term refinement suggestions. Suggests easier words for hard Sino-Korean words, loanwords, and Japanese-style terms, as confirmation blocks only.
`enable_contested_fix`	off	Turns on contested fixes, guideline-based fixes such as `되세요`, `에 있어서`, and overuse of the plural `-들`.
`disable_bias_check`	off	Turns off the confirmation blocks for hateful or discriminatory expressions. The default (off) means these blocks are on.

You can get the meaning of POS tags from the list_pos_tags tool or check them in the POS tag table. custom_dict_names, which passes custom dictionary names, is used to also apply dictionaries made with the custom dictionary.

Reference resources

Separately from tools, Bareun also provides reference material as MCP resources. If an AI tool supports MCP resources, it can load them by URI and use them as context.

Resource URI	Contents	Authentication
`bareun://pos-tags`	The table of 47 POS tags (code, name, category). Same data as the `list_pos_tags` tool	API key
`bareun://server-info`	Server metadata: name, version, build type, and the list of active tools and resources	API key
`bareun://custom-dicts`	List of custom dictionary domain names registered on the server	A valid API key is required

custom-dicts requires a valid API key

bareun://custom-dicts is server operations information (the list of registered custom dictionaries), so it is rejected if the key is missing or invalid. You can put the domain names you get here into custom_dict_names of analyze_syntax and correct_grammar to apply them.

Custom dictionaries are separated per API key (user), so this list also depends on the key used for the call. For details, see Custom dictionary: separation per API key.

Check server version and configuration

If you read the bareun://server-info resource, you get the server's version, build type, and the list of available tools and resources all at once. It is useful when a client wants to learn right after connecting whether "this server supports spell checking" and "which tools it has".

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

version: the Bareun build version (based on git describe). It shows v3.0.0 for a release tag, and something like v3.0.0-12-g1a2b3c if there are commits after the tag.
build: revision (includes the Korean spell checker) or standard. MCP is provided only by revision builds, so being able to read server-info itself means the server supports spell checking.
tools/resources: the list of tools and resources currently active (reflected automatically according to the build configuration).

A client that does not support resources can get the same information with a direct call. Call the resources/read method with {"uri": "bareun://server-info"}.

Authentication

The Bareun MCP endpoint is protected by an API key. Put the key in every request in one of the following ways. Since 3.4.0, however, initialize and tool-list requests are answered without a key (so that remote MCP directories can list the server and health checks work). Tool calls need a key; without one, the server replies that a key is required.

api-key: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

Requests without an API key are rejected. For issuing API keys and usage, see Using the cloud.

OAuth login (Sign in) is also supported

Tools that use OAuth login, such as VS Code, do not need you to put in a header yourself. When you first connect to the server, a browser login window opens, and you connect by entering your Bareun API key there. Bareun identifies users by API key, so the value you enter in the login window is the API key. Once you sign in, the tool stores the credentials securely so you do not have to enter them again, and the API key does not stay in a config file.

Register in AI tools

How to register a remote MCP server differs a little from tool to tool, but in every case you only need to specify the endpoint address and the authentication (API key header or OAuth login). The endpoint has the form https://<host>:<port>/mcp. The examples below are for Bareun Cloud (https://api.bareun.ai:443). If you installed the Korean spell checker yourself, change it to that server's address (for example, http://localhost:5656). Put your real key in place of YOUR_API_KEY.

Detailed guides per environment

What follows is a summary for quick registration. For step-by-step instructions, OAuth login, and troubleshooting in each environment, see the per-environment guides: Claude Code · Claude Desktop · VS Code · Cursor · Codex CLI · ChatGPT · Other clients.

Add it with one line in the terminal.

claude mcp add --transport http bareun https://api.bareun.ai:443/mcp \
  --header "api-key: YOUR_API_KEY"

After adding, you can check the connection status with claude mcp list and the tool list with /mcp during a conversation.

Create .vscode/mcp.json in the workspace, or run MCP: Add Server from the command palette.

{
  "servers": {
    "bareun": {
      "type": "http",
      "url": "https://api.bareun.ai:443/mcp",
      "headers": { "api-key": "YOUR_API_KEY" }
    }
  }
}

If you set the chat to agent mode, the model can use the registered tools. If you drop headers and leave only url, VS Code opens a browser login window on first connection and goes through OAuth login (see the VS Code guide for details).

Add it to the project's .cursor/mcp.json (or the global ~/.cursor/mcp.json).

{
  "mcpServers": {
    "bareun": {
      "url": "https://api.bareun.ai:443/mcp",
      "headers": { "api-key": "YOUR_API_KEY" }
    }
  }
}

If the bareun server and its tools appear on the Settings → MCP screen, you are connected.

Add it under Settings → Developer → Edit Config (claude_desktop_config.json). Claude Desktop connects remote HTTP servers that need header authentication through the mcp-remote bridge (Node.js required).

{
  "mcpServers": {
    "bareun": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://api.bareun.ai:443/mcp",
        "--header", "api-key: YOUR_API_KEY"
      ]
    }
  }
}

(On some plans, you can also add it directly by URL under Settings → Connectors.)

You must turn on developer mode in settings to create a custom connector (Settings → Apps & Connectors → Advanced). Then create a connector and enter the values below.

Item	Value
MCP server URL	`https://api.bareun.ai:443/mcp`
Authentication	OAuth (enter your Bareun API key in the login window that opens when you connect)

Whether developer mode is available depends on your account plan, and on Business and Enterprise the workspace administrator must allow it first (see the ChatGPT guide for details).

Add a [mcp_servers.bareun] table to ~/.codex/config.toml and specify url. We recommend keeping the API key as an environment variable token.

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

Set the key with export BAREUN_API_KEY="YOUR_API_KEY" before running. You can also register it with a static header (http_headers = { "api-key" = "..." }) or the mcp-remote bridge (see the Codex CLI guide for details).

After registering, restart the AI tool and analyze_syntax, analyze_syntax_raw, tokenize, list_pos_tags, correct_grammar, and search_dict appear in the list of available tools. Now you can ask the agent something like "Correct this sentence with Bareun".

Check that the connection works

Most MCP tools have a screen that shows the registered servers and tools. If the bareun server and its tools appear there, the connection is working. If they do not appear, check that the endpoint address ends with /mcp and that the API key header is included.

Connection test (for developers)

To quickly check that registration worked, you can inspect the endpoint directly with the official MCP Inspector (Node.js required).

npx @modelcontextprotocol/inspector

In the Inspector, set Transport to Streamable HTTP, set URL to https://<host>:<port>/mcp, and add api-key: YOUR_API_KEY to the headers. When you connect, you see the list of tools and resources and can click each tool to call it.

MCP runs on JSON-RPC 2.0, so you can also call it with ordinary HTTP tools such as curl. A tool call request looks like the following (an example to aid understanding).

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

Order for direct calls

When you call with curl directly, first start a session with initialize, and then send the Mcp-Session-Id from the response headers along with later requests. If you use MCP Inspector or an AI tool that supports MCP, this procedure is handled automatically, so you only need to care about the tool calls.

Frequently asked questions

Q. Do I need to open a new port or install a separate program to use MCP?

No. The /mcp path on the same address where the Bareun server already listens is the MCP endpoint. You can use it right away with no extra port or separate installation.

Q. Can I use MCP with a Bareun build for morphological analysis only?

No. MCP (the /mcp endpoint) is provided only by Bareun builds that include the Korean spell checker. A Bareun build for morphological analysis only has no /mcp endpoint. A Bareun build that includes the Korean spell checker provides all of the analyze_syntax, analyze_syntax_raw, tokenize, list_pos_tags, correct_grammar, and search_dict tools, and you can use them in the same way with the on-premises Korean spell checker.

Q. How does authentication work?

Put the API key you were issued in the api-key header, or send it in the form Authorization: Bearer <key>. Either way works. Requests without a key are rejected.

Tools that support OAuth login (such as VS Code) open a browser login window on first connection. Enter your Bareun API key there. Bareun identifies users by API key, so the value you enter in the login window is the API key, and once you sign in, the tool stores the credentials. For the login steps in each environment, see the per-environment registration guides.

Q. What is the difference between full and compact in analyze_syntax?

full returns the complete result including morphemes, POS, and positions, and compact returns a one-line summary joining surface/POS pairs with spaces. compact is handy when a person wants to read the result quickly or you want to save tokens.

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

Call the list_pos_tags tool to get the code, name, and category of the 47 POS tags at once. You can also read the same content as the bareun://pos-tags resource, so an AI tool can load it as reference material when interpreting analysis results.

Q. The position values in the analysis result are not what I expected.

Morpheme position values are counted in the unit set by the encoding option. The default is utf32, which counts characters. If you process the result in JavaScript or Java, call with utf16; in Go or C++, call with utf8.

Q. How do I check the server version or supported tools?

If you read the bareun://server-info resource, you get the server version, build type, and the list of active tools and resources at once. A client that does not support resources can call resources/read with {"uri": "bareun://server-info"}.