Connect an agent

An agent reaches Xianyun by launching xianyun-mcp and talking MCP to it over standard input and output. This page covers the setup. How the MCP server works explains what you get.

The one rule: working directory

Every tool call resolves its configuration the way the terminal command does, by searching upward from the working directory of the xianyun-mcp process. If the client starts the server somewhere else, every call fails with no caproni.yaml found in current directory or any parent directory up to home directory.

Start the server in your project directory. Check where your client starts it; opencode has a cwd option for exactly this.

opencode

Add the server to opencode.json in your project, or to your global config:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "xianyun": {
      "type": "local",
      "command": ["xianyun-mcp"],
      "enabled": true
    }
  }
}

If xianyun-mcp isn’t on your PATH, use the full path as the first element of command. opencode registers each MCP tool with the server name as a prefix, so xianyun_status appears as xianyun_xianyun_status.

Claude Code

$ claude mcp add xianyun -- xianyun-mcp

Run it from your project directory.

Other clients

xianyun-mcp can edit the configuration of four editors for you. Each has enable, disable, and list subcommands that change that client’s own config file:

$ xianyun-mcp mcp claude list     # Claude Desktop
$ xianyun-mcp mcp vscode list
$ xianyun-mcp mcp cursor list
$ xianyun-mcp mcp zed list

For any other MCP client, register a local server whose command is xianyun-mcp and which speaks stdio. The server also accepts xianyun-mcp mcp start, which is the same thing spelled out.

Prefer stdio. The HTTP transport has open security problems; see Security.

Check that it works

Ask your agent to call xianyun_version, then xianyun_config_validate. A successful call returns the command’s output and exit code:

{
  "exit_code": 0,
  "stderr": "",
  "stdout": "✓ Configuration is valid (v2)\n  • 0 deployers configured\n  • 0 repositories defined\n  • 0 reloaders configured\n\n"
}

If the call fails instead, see Troubleshooting.

Tell the agent how to use it

Agents behave better when the project says what the tools are for. A snippet for your AGENTS.md:

## Local cluster

Use the `xianyun` MCP tools to manage the local Kubernetes environment.

- Call `xianyun_config_validate` before `xianyun_up`, and `xianyun_status` after it.
- Read `xianyun_logs` and `xianyun_doctor` output before retrying a failed step.
- Ask me before calling `xianyun_destroy` or `xianyun_update-etc-hosts`.
- Don't edit `xianyun.yaml` hooks without telling me; hooks run commands on my machine.

The tool names above are what the server exports. Your client may add a prefix.

Keyboard shortcuts