velodb-mcp-server: Instructions file for Codex

AGENTS.md — Agent Playbook for Installing velodb-mcp-server

Audience: AI agents (Claude Code, Cursor, Codex, etc.), not humans. When a user asks you to install this MCP server and connect their VeloDB cluster, follow this playbook exactly. The user should never need to read any documentation — you do all the work; the user only answers a few questions.

Trigger phrases

The user may say something like:

• "Install this MCP server per the README and tell me how to connect my VeloDB cluster."
• "Set up the VeloDB MCP for me."
• Any equivalent phrasing in any language (e.g. a Chinese request such as "install this MCP and tell me how to connect my VeloDB cluster")

If the request mentions installing/setting up this MCP server or connecting a VeloDB cluster, you are in the right place. Read this whole file first, then execute the steps in order.

Overview of what you will do

Step 0  Ask the user 2 short questions (connection info, install location)
Step 1  Detect the platform and download the matching release tarball
Step 2  Write the VeloDB FE address into mcp-server.toml
Step 3  Start the server in the background and health-check it
Step 4  Register the MCP server with the user's AI client (e.g. Claude Code)
Step 5  Verify end-to-end and report success

Do not skip steps. Verify each step before moving on. If a step fails, consult the Failure handling table.

---

Step 0 — Collect information (ask once, then proceed)

Ask the user exactly these questions (in one message), then wait for the answers:

1. Connection info: the VeloDB FE host (endpoint domain, IP, or hostname) and MySQL-protocol port, plus a username and password.
2. Install location: on this machine (where you are running), or on a remote server? If remote, ask how you can reach it (e.g. SSH access).

Rules:

• VeloDB Cloud, VeloDB Enterprise, and Apache Doris all speak the same MySQL protocol, so this server connects to any of them the same way — do not ask which deployment type the user has; you only need the FE address and credentials.
• The default MySQL-protocol port is 9030. Do not ask about it separately; only confirm if the user gave a non-default port.
• The machine running this MCP server must be able to reach the FE host:9030. If the FE address is a private IP and the user wants to install on a laptop that cannot reach it, tell them and ask for a reachable install location instead.
• Never print the user's password back in chat output beyond what is necessary to complete the setup commands.