Skip to content

Agents, JSON and MCP

The same yofix binary you use by hand is designed to be driven by scripts and AI agents. Three things make that reliable: a stable JSON envelope, stable error codes, and a built-in Model Context Protocol (MCP) server.

Stable JSON output

Pass --json to any command and you get a predictable envelope. Human progress always goes to stderr, so stdout stays parseable even without --json.

Terminal window
yofix deploy --prod --json | jq -r '.data.productionUrl'
yofix ls --json | jq '.data[] | select(.status == "ready")'

The envelope shape (success and error) and its guarantees are documented in Global options and output.

Stable error codes

Every failure carries a machine-readable YF_* code and a numeric exit code, so an agent never has to string-match an error message:

Terminal window
yofix deploy --prod --json
# on failure: { "ok": false, "error": { "code": "YF_DEPLOY_BUILD_FAILED", ... }, "exitCode": 10 }

See the exit code table and the Error reference for every code with causes and fixes.

MCP server

yofix mcp serve runs a Model Context Protocol server over stdio, exposing deployments, logs, environment variables, and VRT as tools that an MCP client can call directly. Wire it into Claude Code, Cursor, or any MCP client:

mcp config
{
  "mcpServers": {
    "yofix": {
      "command": "yofix",
      "args": ["mcp", "serve"]
    }
  }
}

The server uses the same stored credentials as the CLI, so run yofix login once first. In a headless agent environment, set YOFIX_TOKEN instead.

Calling the API directly

When a command does not cover what you need, call any endpoint with auth and team headers already wired:

Terminal window
yofix api list                                   # every endpoint from the OpenAPI spec
yofix api call GET /v1/projects                  # call an endpoint
yofix api call POST /v1/projects/:id/deployments --data '{"target":"preview"}'
yofix api curl /v1/projects                      # print the equivalent curl, do not run it

The full machine-readable API surface is published at:

  • OpenAPI spec: https://app.yofix.ai/v1/openapi.json
  • Agent index: https://app.yofix.ai/llms.txt
  • Full agent reference: https://app.yofix.ai/llms-full.txt

Next