Core Concepts

Conceptual model shared by Atlas MCP, SDK, and API.

Atlas requests run under an Atlas user identity. Each surface sends an input string and explicit context. Atlas returns an answer plus typed result collections.

​

Request

A request is an Atlas API payload with an input string and optional context.

Request context is data supplied by the caller. Supported context includes selected files, uploaded file IDs, inline text, session IDs, and metadata.

​

Run Lifecycle

A run is an execution record for work that needs status, event streaming, cancellation, or later retrieval.

SDK and API expose run lifecycle operations directly. MCP exposes progress through progress notifications and returns final results through its normal result path.

​

Runtime

Surface	Local boundary	Remote boundary
MCP	Local MCP accepts host-approved file:// URIs.	Remote MCP accepts Atlas file URIs, inline text, and base64 blobs.
SDK	Local SDK calls can attach paths, streams, and inline text.	Hosted SDK calls send uploaded file IDs and request payloads to Atlas APIs.
API	No local file access.	Receives HTTP payloads, validates auth, executes operations, and returns result envelopes.

Local runtimes convert explicit local inputs into uploaded files or inline request fields before the remote API call. Remote runtimes cannot read a user’s filesystem.

​

Auth

Atlas evaluates access under a user identity. Local MCP authenticates during setup. Remote MCP authenticates the connected user on the MCP connection. SDK and direct API integrations also identify the application.

Developer credentials belong in trusted application environments.

​

Response

Atlas responses contain an answer and result collections.

Field	Meaning
objects	Compact Atlas records, such as issues, runs, systems, and assets.
files	Uploaded, attached, or generated file handles.
artifacts	Generated reports, summaries, exports, tables, or bundles.
actions	Proposed operations that require approval before execution.
links	URIs for full object retrieval, file or artifact download, and Atlas resource links.

​

Files

Files can enter Atlas as selected local paths, uploaded Atlas file IDs, streams, inline text, or small base64 blobs.

Local surfaces resolve local paths before the remote API call. Remote surfaces use Atlas file IDs or inline content.

Returned files and artifacts are handles. Callers fetch content through the surface-specific download path: MCP resources/read, SDK download helpers, or API download endpoints.

​

Streaming

Interactive surfaces stream progress to the user interface. Programmatic surfaces expose structured progress through MCP progress notifications, SDK async run events, and API Server-Sent Events for run events.

​

Sessions

Sessions preserve continuity across related requests. Use a session when a workflow needs follow-up requests, shared files, returned results, run lifecycle state, or application state across user interactions.