---
name: iqobi
description: Create and edit iqobi draft apps through the public Builder API. Use when asked to build an iqobi app, list owned apps, inspect package files, validate code, or save a draft outside Studio.
---

# Build an iqobi app

Use the Builder API at `https://api.iqobi.dev/builder/mcp`. It accepts MCP JSON-RPC
over HTTPS and needs no CLI or npm package. Existing MCP clients can use the
connection link from Settings directly.

## Connect

1. Have the person open [AI assistants](https://iqobi.dev/?settings=mcp),
   sign in, choose an assistant, and create a connection.
2. Treat the complete connection link as a secret. For an MCP client, paste
   that link and choose no sign-in. For HTTP requests, use the secret after
   `/builder/mcp/k/` as the `IQOBI_BUILDER_TOKEN` environment variable.
3. Keep the token out of app files, source control, chat replies, and logs.
   Only send it to this environment's platform or API origin. Production and
   staging have separate accounts and tokens. A person can revoke a connection
   in the same Settings page.

The bearer can read and change the account's draft apps and delete apps that
have never been published. Publication requires the person in Studio.
This is separate from an individual app's data-tools connection.

Set the API origin for the environment that served this skill:

```sh
export IQOBI_API_ORIGIN='https://api.iqobi.dev'
```

Discover the current tools before writing code:

```sh
curl --fail-with-body --silent --show-error \
  "$IQOBI_API_ORIGIN/builder/mcp" \
  -H "Authorization: Bearer $IQOBI_BUILDER_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

For MCP initialization, send `initialize` with `protocolVersion` set to
`2025-06-18`, then `notifications/initialized`. HTTP requests are stateless;
no session ID is needed. A notification without `id` returns HTTP 202.

## Read the contract

Fetch [the complete app contract](https://api.iqobi.dev/sdk/v0/skill) before building.
It contains the SDK references and the same package rules Studio uses.
[SDK declarations](https://api.iqobi.dev/sdk/v0/types) return `{digest, files}`.
These reads need no token. The contract response's `Iqobi-Skill-Identity`
header identifies the builder instructions.

Only `app.js` or `app.ts` is required. Render into `#app` with React
`createRoot` or export `mount(root)`. The platform supplies `index.html`,
`server.js`, and `schema.json` when absent. Use `.js` or erasable `.ts`,
not JSX. Apps have no arbitrary network access, secrets, or npm dependencies.

The contract is written for the `iqobi` CLI and Studio. Through this API,
call `check_files` where it says `iqobi check`, save with `create_app` or
`write_files` where it says `iqobi push`, and read the inlined guides instead
of `readGuide`. Studio journey tools are unavailable. External acceptance checks compatibility and mounting; it
does not establish that every user interaction works.

## Work on a draft

Call tools with a `tools/call` request. For example, list owned apps:

```sh
curl --fail-with-body --silent --show-error \
  "$IQOBI_API_ORIGIN/builder/mcp" \
  -H "Authorization: Bearer $IQOBI_BUILDER_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_apps","arguments":{}}}'
```

For a new app, call `check_files` with `files`, a map of relative paths to
UTF-8 contents, and optional `name`. Repair diagnostics until `passed` is
true. Then call `create_app` with `name`, `files`, optional `summary`, and a
fresh UUID `requestId`. Retain that UUID before sending. Reuse it to recover
an uncertain creation response without creating another app.

For an existing app, use `list_files` with `appId` and `read_file` with
`appId` and `path`. They read the draft by default; `channel: "live"` reads
the published version. Stored packages contain JavaScript, so read `app.js`
after submitting `app.ts`.

Save related edits together with `write_files`, passing `appId` and `files`.
It merges those files into the current draft. Optional `delete` removes
paths; `replace: true` replaces the entire package. Use replacement only
when you have the complete package. Every save validates the resulting
package and saves nothing on failure. `write_file` and `delete_file` are
available for a single path.

Parse the JSON-RPC envelope first. An `error` is a protocol failure. A tool's
`result.content` contains a text block whose `text` is itself JSON. Parse it
and inspect `result.isError`; HTTP 200 alone does not mean the tool succeeded.
Validation failures carry `passed: false` and `diagnostics`.

On `draft_changed`, re-read the draft and reconcile before retrying. Do not
blindly retry saves after a lost response; read the saved files first.
HTTP 401 requires a valid connection. HTTP 429 includes `Retry-After`.
Compiler failures may return `compiler_busy` or `compiler_unavailable` with
`retryable: true`. Requests are limited to 4 MiB and tool results to 256 KiB.
`write_files`, `write_file`, and `delete_file` refuse a file over 256 KiB or
an invalid path with a JSON-RPC `-32602` error and save nothing.

Return the saved app's [Studio link](https://iqobi.dev/apps/APP_ID/edit),
replacing `APP_ID` with the returned `appId`. The person previews and publishes
there. Report the saved draft and any unverified behavior accurately.