Atlas Connect — Overview

Atlas Connect lets AI agents and external tools query your file lineage — but on your terms. Every operation is read-only. Every query is logged. The agent sees what you’ve chosen to track, nothing more, and it cannot modify your data. Connect is an interface to Atlas, not an extension of it.

Why This Exists

Atlas builds a rich, structured record of your files: content hashes, timestamps, paths, forks, lineage chains. That metadata is valuable — not just to you, but to tools that can interpret it. An AI agent connected to Atlas can answer questions like “what plugins did I use most this year?” or “where did this sample come from?” by querying your local graph directly.

The alternative is worse: agents that scan your filesystem themselves, build their own indices, phone home to cloud services, and operate on data you never consented to share. Connect makes Atlas the single source of truth and the single point of control.

Trust Model

Connect is designed around three constraints:

Read-only. Agents cannot create, modify, or delete anything in Atlas. No edges added, no history altered, no files touched. The entire tool surface is query-only. This is enforced at the protocol level — there are no write operations to call.

Audited. Every query an agent makes is recorded in the agent_audit_log table — tool name, arguments, result count, duration, and timestamp. You can review exactly what an agent asked and when. The audit log is queryable through the same tools you already know:

atlas audit              # Recent agent queries
atlas audit --today      # Today's activity
atlas audit summary      # Usage breakdown by tool

Nothing happens in the dark.

Scoped. Agents see only what you choose to expose. Connect Scope lets you restrict agent visibility independently of what Atlas watches — you can track a directory without exposing it to agents. The [connect.scope] config supports allow lists (restrict agents to specific paths) and deny lists (hide specific paths or patterns). Deny always wins over allow.

On first run, Atlas seeds sensible deny defaults — ~/.ssh, ~/.gnupg, ~/.aws, credential files, and .env files are hidden from agents automatically. You can review and manage scope rules with atlas connect scope, and all changes are dry-run by default with --confirm to apply.

Your watch boundaries are your outer access boundary. Connect Scope is the inner one.

Local-First

Connect runs entirely on your machine. The MCP server is a local process — either attached to stdin/stdout as a subprocess, or listening on 127.0.0.1 with no network exposure. There is no cloud relay, no API key, no account, no telnet home.

The audit log is stored in the same SQLite database as your lineage data. You own it. You can query it, export it, back it up, or delete it with standard tools. If Atlas disappears tomorrow, your audit history is still a readable SQLite table.

The MCP feature is entirely optional. Build Atlas with --no-default-features and the MCP dependencies (rmcp, tokio, schemars, axum) are excluded completely. The CLI agent path (--json) works regardless — it’s just Atlas commands with structured output. No additional runtime, no additional attack surface.

Integration Paths

There are two ways to connect an agent to Atlas:

CLI with --json — The simplest path. Every Atlas command supports --json for structured output. The agent calls Atlas as a subprocess and parses the response. Zero additional dependencies, works with any agent that can run shell commands. This is Atlas’s existing interface with a flag — nothing new to trust.

MCP server — The protocol-native path. Atlas runs an MCP server exposing 14 read-only tools. Richer than CLI — supports aggregate queries, edge search, and temporal filtering in a single call. Works with any MCP-compatible client (Claude Code, Cursor, and others).

See Setup & Reference for configuration, the full tool list, and examples.

What Agents Can Query

Through Connect, an agent has access to Atlas’s full query surface — the same data you can access through the CLI, nothing more:

Search and discover — Find files by name, path, hash, or extension across watched directories
Trace lineage — Follow a file’s history forward or backward through its full lifecycle
Analyze dependencies — See what a file needs (inputs) and what it produces (outputs)
Cross-project analysis — Aggregate queries across hundreds of projects in a single call
Impact analysis — Determine what would break if a file changes
Find broken references — Surface unresolved links and missing dependencies
Temporal queries — Filter by date ranges and distinguish between witnessed and scan-discovered events

Agents cannot access file contents. Atlas hashes files but does not read, parse, or index their contents. An agent querying Connect knows that a file exists and how it relates to other files — not what’s inside it.

Data Portability

The audit log and all Connect metadata live in Atlas’s SQLite database — the same file, the same format, the same ownership model as the rest of your data. There is no separate service, no separate data store, no separate backup to worry about.

If you move your .atlas/atlas.db to another machine, your audit history comes with it. If you open it in a SQLite browser, the agent_audit_log table has clear column names and is immediately readable. The data outlives the software.