MCP server definition syntax

An MCP server definition is a TOML file. The file name and name field must match. For example, the definition for echo lives at:

$XDG_DATA_HOME/repo-local-tools/mcp-servers/echo.toml

A minimal definition is:

name = "echo"
command = "python"

A definition with arguments and environment variables is:

name = "echo"
command = "python"
args = ["-m", "example"]

[env]
MODE = "test"

Fields are interpreted as follows:

• name: Required string. This is the MCP server name written into generated client configuration. It must match the file name without .toml.
• command: Required string. This is the executable command used to start the MCP server.
• args: Optional list of strings. These are passed to command in order.
• env: Optional TOML table. Each key and value must be a string environment variable.

During installation, the definition is rendered into the same mcpServers shape for each supported client:

{
  "mcpServers": {
    "echo": {
      "args": ["-m", "example"],
      "command": "python",
      "env": {
        "MODE": "test"
      }
    }
  }
}

The generated MCP files are:

.mcp.json
.codex/mcp.json
.factory-droid/mcp.json
.cursor/mcp.json