CLIツールをMCPサーバーに作り替える──単純なツール移植では済まなかった設計転換A hands-on account of converting a CLI tool into an MCP server, revealing that…

Converting a command-line tool into a Model Context Protocol (MCP) server sounds like a mechanical task, but a recent hands-on account published on Zenn argues that it is closer to a redesign than a port. The topic matters because MCP has quickly become a common way to expose existing functionality to large language models such as Anthropic's Claude, and many teams assume their battle-tested CLI utilities can be wrapped in a thin adapter. The author's experience suggests that assumption often breaks down.

MCP, introduced by Anthropic in late 2024 and since picked up by a range of vendors, is an open standard that lets AI clients discover and call external tools, read resources, and use predefined prompts. An MCP server typically communicates over stdio or an HTTP-based transport and describes each tool with a name, a natural-language description, and a JSON Schema for its inputs. That description is the critical difference from a CLI: where a human reads a man page or experiments with flags, the model reads the tool's metadata and decides, on its own, when and how to invoke it.

The article frames the first major shift around interface contracts. A CLI is designed for a human operator who tolerates terse flags, positional arguments, and output formatted for a terminal. An MCP tool is consumed by a model that needs unambiguous descriptions, well-named parameters, and structured results it can parse. Options that worked as shorthand for humans can confuse a model, and richly formatted terminal output—colors, tables, progress indicators—becomes noise or wasted tokens. The author reportedly found that tool descriptions and parameter naming carry more weight than any single line of business logic, because they determine whether the model calls the tool correctly at all.

State management is the second area the piece highlights. Command-line programs frequently rely on ambient context: the current working directory, environment variables, configuration files, and a fresh process for every invocation. An MCP server, by contrast, is often a long-lived process handling multiple requests, sometimes across a session, and it cannot assume the same implicit environment. The author describes having to make previously implicit state explicit—passing paths and context as parameters rather than depending on where the command happened to run—so that each tool call is self-describing and reproducible.

Granularity also required rethinking. A single CLI command with a dozen flags can map poorly to model-driven usage; the account suggests that breaking broad commands into several focused tools, each with a clear purpose, tends to work better, while too many overlapping tools can overwhelm the model's selection process. Error handling shifts as well: exit codes and messages on stderr, adequate for scripts and humans, are replaced by structured errors that the model can interpret and potentially recover from.

These observations echo broader industry patterns. Official MCP SDKs exist for TypeScript, Python, and other languages, and higher-level frameworks such as FastMCP aim to reduce boilerplate, but they do not resolve the design questions the article raises. The challenges also resemble those long familiar from API design and from the tool-use or function-calling interfaces offered by other model providers, where clear schemas and descriptions are essential. In that sense, MCP does not invent the problem so much as make it unavoidable for anyone exposing existing tooling to an autonomous agent.

The practical takeaway, as presented, is that teams planning similar migrations should budget for design work rather than treating it as a wrapping exercise. Reusing core logic from a CLI is often feasible, but the surrounding contract—naming, descriptions, parameters, state, and error semantics—likely needs to be reconsidered from the model's perspective. As MCP adoption grows, firsthand accounts like this one appear useful for setting expectations, though the specifics will vary with each tool's complexity and its intended role inside an AI workflow. Readers weighing a migration may find the most value in treating the CLI's internal logic as a reusable core while deliberately rebuilding the layer that an agent actually sees.