How the MCP server works

xianyun-mcp exposes 20 of the CLI’s commands as MCP tools. The list is a reviewed allowlist, not the whole command tree, and a test fails the build if a new command is added without being classified.

One call, one command

When a client calls a tool, the server runs the matching xianyun command in its own working directory and returns what it printed:

{ "stdout": "...", "stderr": "...", "exit_code": 0 }

A non-zero exit code also marks the result as an error. The executable that runs is xianyun-mcp itself, called with the matching subcommand, so there’s no second binary to keep in step.

Every tool takes the same two inputs:

Input	Type	Meaning
`args`	list of strings	Positional arguments, for example process names for `xianyun_logs`
`flags`	object	Named options, with underscores in place of dashes: `{"dry_run": true}` for `--dry-run`

The tool reference lists the flags each tool accepts.

Three tiers

Tier	Tools	Behaviour
Read-only	7	Report state. Safe to call freely.
State-changing	8	Change something local and reversible: start a cluster, pull repositories, merge a kube context. They run without a prompt.
Gated	5	Tear down state, rewrite `/etc/hosts`, or touch the trust store. They need confirmation first.

What isn’t exposed

Six commands are left out on purpose.

tool runs any executable you name. This is the shape of glab #8153, where an unreviewed command became an arbitrary-execution primitive.
kubectl forwards every argument to the real kubectl, with no schema to check them against.
k9s needs a terminal and never returns.
stern streams until interrupted. xianyun_logs covers the same need.
run supervises edit-mode processes until interrupted, which doesn’t fit a request and response call.
edit-mode-process-supervisor is internal plumbing that run starts.

You can still run all six from a terminal. For kubectl, xianyun kubectl get pods is the same command your agent can’t run.

Transports

Standard input and output is the default and the one to use. xianyun-mcp with no arguments, or xianyun-mcp mcp start, serves it.

Streamable HTTP is xianyun-mcp mcp stream. Read Security first: it listens on all interfaces by default and has no authentication.

xianyun-mcp mcp tools writes the current tool list to ./mcp-tools.json, which is what the repository’s snapshot test checks against.

Side effects to know about

xianyun_ca_inspect is in the state-changing tier rather than the read-only one because it creates the dev CA’s key pair on disk the first time it runs.
xianyun_up, xianyun_deploy, and xianyun_update can run lifecycle hooks from your configuration, and the configuration can come from remote fragments and cloned repositories. Treat the config as code. See Security.