DEVELOPER GUIDE · LOCAL STDIO

Connect your workspace with MCP

Use your MCP host to read an existing Smaltino task, with optional, explicitly enabled Nano image tools. This guide describes the source service in services/mosaic-mcp-server.

1. Prepare the local connection

Obtain authorized access to the project source workspace before using this guide. Use that workspace's services/mosaic-mcp-server package; no public download is provided here.
Install Node.js 22 or newer and the workspace's pnpm version. Install the workspace dependencies from its root with pnpm install --frozen-lockfile before starting the service.
Use a valid Smaltino API Key belonging to your account and this site. Configure it only in your MCP host's protected environment; never commit the value to a repository or place it in a prompt. Manage Smaltino API Keys

In your host's local MCP server settings, adapt this stdio configuration. Replace <workspace> with the absolute path to your authorized checkout. The API origin is a configuration example, not proof that production access is active.

{
  "mcpServers": {
    "mosaic": {
      "command": "pnpm",
      "args": [
        "--silent",
        "--dir",
        "<workspace>/services/mosaic-mcp-server",
        "start"
      ],
      "env": {
        "MOSAIC_API_URL": "https://api.smaltino.com",
        "MOSAIC_API_KEY": "<INJECT_FROM_HOST_PROTECTED_ENVIRONMENT>"
      }
    }
  }
}

Replace the Key placeholder through your host's protected environment mechanism. MOSAIC_API_URL must be an HTTPS origin, or loopback HTTP for local use, without credentials, a path or query. API credentials never belong in tool arguments. The write switch is intentionally omitted from this default configuration.

On Windows, if the host cannot launch pnpm directly, configure the installed node binary with the workspace's tsx CLI path and services/mosaic-mcp-server/src/index.ts entry. When loading tsx via node --import, use a file:///C:/... URL for an absolute Windows path.

The MCP host manages the stdio process lifecycle; this service does not start a background daemon. Keep --silent so pnpm does not put script banners on stdout: stdout is reserved for the MCP protocol.

2. Query an existing task by default

`mosaic_get_task`

By default, only mosaic_get_task is registered. Supply task_id from your Smaltino creations; the configured Key must belong to the task's user. The query does not create a generation task or charge generation credits.

{ "task_id": "your-existing-task-id" }

The safe task summary contains id, taskType, title, status, createdAt and updatedAt. Possible statuses are accepted, queued, running, succeeded, failed and canceled.

The summary excludes the raw prompt, private input fields and source-file signatures. Authentication, revoked-Key checks, site scope and task ownership remain enforced by the API.

3. Enable writes only when intended

Writes need both permissions: MOSAIC_ENABLE_TASK_WRITES must be exactly the string true in the host's process environment, and the API Key must have explicit server-side write permission. Omitted, false, TRUE, 1 or whitespace-padded values keep the service read-only. Add the following environment entry only when you intend to expose the write tools.

"MOSAIC_ENABLE_TASK_WRITES": "true"

The local switch cannot upgrade a read-only Key. Tool annotations and local enablement do not prove host human review, budget approval or a locked price. This page has no write-enablement control.

The optional tools support only image.generate.text-to-image with kie-nano-banana-2 (Nano Banana 2). They do not expose the site's full model or media catalog.

mosaic_estimate_task: Accepts prompt and optional aspect_ratio. Returns the current credit estimate without creating a task, reserving credits or locking a later price. The server's Key-use audit may change. Do not include idempotency_key in an estimate.
mosaic_create_task: Accepts prompt, optional aspect_ratio and required idempotency_key. Creates or recovers your task; the server decides the actual charge. The example below is a create input, not an instruction to submit it.

{
  "prompt": "A small paper boat on a calm blue lake",
  "aspect_ratio": "auto",
  "idempotency_key": "Original-Key_01"
}

MCP tool fields use snake_case. Unknown fields are rejected. Keep prompt nonblank and at most 5000 JavaScript UTF-16 code units; its original text is preserved. aspect_ratio can be omitted (equivalent to auto). Supported ratios: auto, 1:1, 4:3, 3:4, 16:9, 9:16, 2:3, 3:2, 4:5, 5:4, 21:9, 1:4, 4:1, 1:8, 8:1.

Provide your own explicit idempotency_key matching ^[A-Za-z0-9._~-]{1,64}$. It is sent unchanged as Idempotency-Key. The same user, key and identical request body recover the original task and accepted amount; changing the body with the same key is a conflict. An estimate is not a price lock, and there is no maxCredits promise.

The independent CLI is a separate entry: its JSON input uses aspectRatio, while MCP tools use aspect_ratio. pnpm --silent start is the MCP protocol entry, not a CLI command. Consult the workspace README for CLI usage.

4. Handle errors and unknown results

invalid_api_key: The Key is invalid, revoked or scoped to another site. Configure a valid Key without exposing it in tool inputs.
task_not_found: The task does not exist or does not belong to the configured Key's user. Check the ID in your creations.
api_not_configured: The query API has no configured control database. The deployment owner must activate it; changing the local write switch cannot fix it.
api_unavailable: The query encountered a network failure, timeout or forbidden redirect. Check the API origin before trying again.
api_key_read_only: The server rejected the write permission. A local flag does not upgrade the Key.
invalid_api_task: The server rejected the write input. Check the approved prompt, field names and aspect ratio.
api_task_idempotency_conflict: This key was used with a different body. Check the original request; do not silently replace the key to evade recovery.
insufficient_credits: The server rejected the request for insufficient credits. An earlier estimate did not reserve a price or balance.

Body-size, content and rate-limit rejections use safe error codes. Invalid or oversized GET summaries use invalid_api_response or api_response_too_large. Remote error bodies are not passed through; do not treat a failed query as a failed generation.

Requests have a 30-second timeout, redirects are forbidden and responses are limited to 64 KiB. The Key is sent only in the Bearer header, and successful outputs are filtered to the safe contract.

Related Smaltino pages

Manage Smaltino API Keys Nano Banana 2 model page Text to Image studio

This is static connection guidance. Reading this page does not call MCP or create a task. Local tests do not establish production Key activation, host human review, real payment, paid generation or provider output quality.