Connect a local tool

Apps, scripts, and agents can use the running Atlas app through its local HTTP API or MCP connection. Provider accounts stay in Atlas. Your tool sends commands and receives results.

Find the local connection

Atlas listens on 127.0.0.1, using the first free port from 17390 through 17399. Scan that range with a short timeout and check that the ping response has name: "atlas-ai-api". Do not read Atlas's database or settings files to find it.

GET http://127.0.0.1:17390/ai/v1/ping

{
  "ok": true,
  "name": "atlas-ai-api",
  "version": 1,
  "appVersion": "<running Atlas version>",
  "mcp": "/ai/v1/mcp"
}

Ping checks whether Atlas is running. Read Image generation for model discovery, request settings, and saved results.

Get permission to send commands

While AI access is enabled, a local client can call GET /ai/v1/pair. The response contains { ok: true, token }. Keep that token in your local app or server. Send it in Authorization: Bearer <token> on later calls.

The current pairing route lets local programs connect without a separate approval dialog. Treat the token as access to the commands shown by GET /ai/v1/describe, including file and metadata writes. Turning off AI access stops the server.

Send commands

Call GET /ai/v1/describe after connecting to read the running app's command catalog. Each entry includes its arguments, description, and whether it writes data. Use POST /ai/v1/command for both reads and writes.

const response = await fetch(baseUrl + "/ai/v1/command", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer " + token,
  },
  body: JSON.stringify({ command: "generation_options", args: {} }),
});
const body = await response.json();
if (!response.ok || !body.ok) throw new Error(body.error);
const options = body.result;

Successful commands return { ok: true, result }. Rejected commands return { ok: false, error } with HTTP status 400. Authentication failures return 401. A job accepted by a generation command can still fail later, so also check its returned state.

Set folder covers

Use save_folder_thumbnail to keep covers during a migration or replace covers in folders you already imported. Check that the command appears in /ai/v1/describe. The target must be an existing folder in Atlas. The image can live anywhere on the same computer, including outside that folder. Both paths must be absolute.

{
  "command": "save_folder_thumbnail",
  "args": {
    "folderPath": "D:/Artwork/Chapter-01",
    "imagePath": "D:/Cover-Exports/Chapter-01.png"
  }
}

Atlas saves a centered square cover and updates the open app. This replaces the current cover. It does not rename, move, or change the source image. It does not copy the source into the target folder. Each save applies to that folder only, including a project root when that is the target.

Optional offsetX and offsetY values range from -100 to 100, with 0 as the center. zoom ranges from 1 to 5 and defaults to 1. The values use the same crop controls as Atlas's folder cover picker. Source images are limited to 50 MB and 40 million pixels. Keep the source file available so Atlas can rebuild the cached cover if needed.

Apply covers to many folders

Supply one folder and image pair for each cover. Wait for each response before sending the next. Atlas accepts one cover save at a time and rejects concurrent saves. A failure leaves earlier successful saves in place, so keep a record of any rows you need to retry.

const covers = [
  { folderPath: "D:/Artwork/Chapter-01", imagePath: "D:/Cover-Exports/Chapter-01.png" },
  { folderPath: "D:/Artwork/Chapter-02", imagePath: "D:/Cover-Exports/Chapter-02.png" },
];

for (const args of covers) {
  const response = await fetch(baseUrl + "/ai/v1/command", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer " + token,
    },
    body: JSON.stringify({ command: "save_folder_thumbnail", args }),
  });
  const body = await response.json();
  if (!response.ok || !body.ok) {
    throw new Error(args.folderPath + ": " + body.error);
  }
  console.log("Cover saved:", body.result.folderPath);
}

Before replacing existing covers, call get_folder_thumbnail_rows with empty arguments and save its result. It reads saved covers without generating new ones. Each row includes folderPath, imagePath for the cached cover, sourceImagePath, offsetX, offsetY, zoom, and updatedAt. To restore a choice, send its sourceImagePath as imagePath to save_folder_thumbnail, along with the saved folder path and crop values. The original source must still exist. Atlas does not keep a separate cover history.

For a migration from another app, export that app's cover images first and map them to the new Atlas folder paths. These commands apply the images you provide; they do not read another app's cover database.

Connect an agent with MCP

Copy the Connection link in Atlas Settings into an MCP client that supports a local HTTP connection. The link points to /ai/v1/mcp and includes the connection token. That client must run on the same computer as Atlas.

Use atlas_describe to read the command catalog. Pass read commands to atlas_query and write commands to atlas_act, with the same { command, args } payload as HTTP. Image generation uses these existing tools.

Next

Read Image generation to load the available models, submit a reference image, and retrieve the finished file.