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 speaks the Model Context Protocol in two forms that expose the same tool catalog:

  • Hosted (recommended): Streamable HTTP at https://api.yofix.ai/v1/mcp. Authenticate with OAuth (a consent page scopes the connection to one team and role) or send a team API key as Authorization: Bearer.
  • Local stdio: yofix mcp serve, using the same stored credentials as the CLI — run yofix login once first, or set YOFIX_TOKEN in headless environments.
mcp config (local stdio)
{
  "mcpServers": {
    "yofix": {
      "command": "yofix",
      "args": ["mcp", "serve"]
    }
  }
}

The tools cover projects, deployments and build logs, promote/rollback, environment variables, domains, VRT runs and screenshots, build incidents and build health, compute providers, PR preview URLs, and offline docs search (search_yofix_docs).

A few behaviours worth knowing when driving the tools:

  • Team scope: every tool (except list_teams and search_yofix_docs) accepts an optional teamSlug. Pass it when a call fails with “Missing user or team context” — team API keys and OAuth connections are already team-bound and don’t need it.
  • Deploy without git: create_deployment packages a local directory over stdio; on the hosted server it returns a single-use upload URL to PUT a tarball to. Pass waitForReady to block until the build reaches a terminal status.
  • Errors are machine-readable: tool errors carry the HTTP status, a YF_* code, and a requestId for support.

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