Atlas Connect — Setup & Reference

Quick Start

CLI path (simplest)

Generate instructions for your AI agent:

atlas agent-setup                    # Auto-detect agent format
atlas agent-setup --format claude    # Claude Code / CLAUDE.md
atlas agent-setup --format cursor    # Cursor / .cursorrules
atlas agent-setup --format copilot   # GitHub Copilot / copilot-instructions.md
atlas agent-setup --format generic   # Any agent

This outputs a markdown block listing all Atlas CLI commands with --json flags. Paste it into your agent’s instructions file. The agent calls Atlas as a subprocess — no server, no protocol, no additional runtime.

MCP path (protocol-native)

Generate MCP configuration:

atlas agent-setup --format mcp

Output:

{
  "mcpServers": {
    "atlas": {
      "command": "atlas",
      "args": ["connect", "start", "--stdio"]
    }
  }
}

Add this to your MCP client’s configuration (e.g., Claude Code’s claude_desktop_config.json, Cursor’s MCP settings). The client launches Atlas as a local subprocess — no network calls, no cloud relay.

Connect Scope

Connect Scope controls which watched paths are visible to agents. It operates independently of what Atlas watches — you can track a directory for your own use without exposing it through Connect.

Configuration

Scope rules live in ~/.atlas/config.toml under [connect.scope]:

[connect.scope]
allow = ["/Users/you/Projects"]
deny = [
    "~/.ssh",
    "~/.gnupg",
    "~/.aws",
    "~/.config/gh",
    "**/credentials*",
    "**/.env",
    "**/secrets*",
]

Allow list — If any entries exist, agents can only see paths under these prefixes. Everything else is invisible.

Deny list — These paths and patterns are always hidden from agents, even if they fall under an allowed prefix. Supports glob patterns (**, *, ?).

Precedence: Deny always wins over allow.

On first run, Atlas seeds default deny entries for common credential locations. These are regular deny entries — you can remove them if you choose.

CLI Commands

atlas connect scope                           # Show current rules
atlas connect scope --json                    # Machine-readable output

atlas connect scope allow /path               # Dry run: show what would change
atlas connect scope allow /path --confirm     # Apply the change

atlas connect scope deny "~/.secrets"         # Dry run
atlas connect scope deny "~/.secrets" --confirm

atlas connect scope remove "~/.ssh"           # Dry run: show what would be exposed
atlas connect scope remove "~/.ssh" --confirm

atlas connect scope reset                     # Dry run: show all rules that would be removed
atlas connect scope reset --confirm           # Clear all scope rules

All scope commands are dry-run by default. Without --confirm, they show what would change without modifying the config. This matches Atlas’s pattern for destructive operations (like atlas forget --pattern).

Behavior

Scoped-out data is invisible, not redacted. Agents receive no indication that filtered data exists — no placeholder counts, no “hidden” markers, no error messages suggesting scope boundaries. From the agent’s perspective, the data simply isn’t there.

MCP Server

Atlas implements the Model Context Protocol via the atlas connect command family. The server exposes 14 read-only tools that mirror and extend the Atlas CLI. There are no write operations — agents cannot modify your data through Connect.

Starting the Server

stdio transport (standard — MCP clients launch Atlas as a subprocess):

atlas connect start --stdio

The server runs on stdin/stdout, speaking JSON-RPC. MCP clients launch it automatically via the config from atlas agent-setup --format mcp. The process has the same filesystem access as your user account but can only execute Atlas read queries.

HTTP transport (for persistent or multi-client connections):

atlas connect start --port 3000

This daemonizes in the background, serving MCP over Streamable HTTP on 127.0.0.1:3000. It binds to localhost only — not exposed to the network. A PID file is written to ~/.atlas/connect.pid.

Stopping and Status

atlas connect stop       # Stop the HTTP daemon
atlas connect status     # Show server state, transport, query count
atlas connect status --json

Available Tools

All 14 tools are read-only and return JSON. No tool can create, modify, or delete data:

Tool	Description	Parameters
`atlas_status`	What Atlas is tracking	none
`atlas_history`	Full file history	`path`
`atlas_search`	Search by name/path/hash	`query`, `limit?`, `offset?`
`atlas_find`	Find by hash, name, path, extension, or duplicates	`hash?`, `name?`, `path?`, `duplicates?`, `extension?`, `path_contains?`, `exclude?`, `limit?`, `offset?`, `date_from?`, `date_to?`, `witnessed_only?`
`atlas_log`	Recent activity	`limit?`, `offset?`, `today?`, `entity?`, `date_from?`, `date_to?`, `witnessed_only?`
`atlas_trace`	Lineage traversal	`path`, `forward?`, `depth?`, `reaches?`
`atlas_inputs`	Dependencies for a file or directory	`path`, `limit?`, `offset?`
`atlas_outputs`	Produced files for a file or directory	`path`, `limit?`, `offset?`
`atlas_impact`	What breaks if this changes	`path`, `depth?`
`atlas_broken`	Unresolved references	`path?`, `limit?`, `offset?`
`atlas_compare`	Content-identity comparison	`path_a`, `path_b`
`atlas_tree`	Fork tree visualization	`path`
`atlas_query`	Aggregate query across entities and edges	`path_prefix?`, `name_pattern?`, `exclude_pattern?`, `edge_type?`, `ref_pattern?`, `group_by?`, `limit?`, `offset?`, `count_only?`, `date_from?`, `date_to?`, `witnessed_only?`
`atlas_edges`	Search edges by reference path, type, or source	`ref_pattern?`, `edge_type?`, `source_path_prefix?`, `pack_name?`, `limit?`, `offset?`, `date_from?`, `date_to?`, `witnessed_only?`

All limit, offset, and depth parameters accept both string ("20") and number (20) values.

Temporal Filtering

Four tools support date-range filtering via date_from and date_to parameters (RFC 3339 format, e.g., "2025-01-01T00:00:00Z"). These filter on the entity’s created_at timestamp — when Atlas first recorded the entity.

The witnessed_only parameter restricts results to entities that Atlas directly observed being created or modified in real-time, excluding entities discovered during an initial scan. This distinction matters: scan-discovered entities have timestamps reflecting when Atlas scanned them, not when the files were originally created. Without this filter, an agent could draw incorrect conclusions about when files were made. In the CLI, unwitnessed timestamps are displayed with a ~ prefix (e.g., ~Dec 12 2025 22:51) to make the uncertainty visible.

Log entries include a witnessed field indicating whether Atlas observed the event in real-time. For atlas_find results, witnessed = !discovered on the entity object.

Aggregate Queries

The atlas_query tool enables cross-project analysis in a single call. It filters entities by path and name patterns, traverses their edges, and returns grouped counts.

Example: Most-used plugins across all Reaper projects

{
  "name": "atlas_query",
  "arguments": {
    "name_pattern": "%.RPP",
    "exclude_pattern": "%.RPP-BAK",
    "edge_type": "input",
    "ref_pattern": "plugin://%",
    "group_by": "reference_path",
    "limit": 10
  }
}

Returns:

{
  "rows": [
    { "key": "plugin://fabfilter/pro-q 4/vst3", "count": 85 },
    { "key": "plugin://cockos/reaeq/vst2", "count": 72 }
  ],
  "total_matching_entities": 149
}

When group_by is "source", each row includes the entity’s human-readable name and path:

{
  "rows": [
    { "key": "abc-123-def", "count": 12, "name": "My Song.RPP", "path": "/Projects/2026/My Song/My Song.RPP" },
    { "key": "fed-456-cba", "count": 8, "name": "Demo Track.RPP", "path": "/Projects/2025/Demo Track/Demo Track.RPP" }
  ],
  "total_matching_entities": 2
}

Parameters use SQL LIKE patterns: % matches any sequence, _ matches one character.

Edge Search

The atlas_edges tool searches edges directly by their reference path pattern, edge type, or source entity location. Useful for finding all plugin references, import paths, or any edge metadata.

{
  "name": "atlas_edges",
  "arguments": {
    "ref_pattern": "plugin://%kontakt%",
    "edge_type": "input",
    "limit": 20
  }
}

Audit Log

Every query made through the MCP server is recorded in the agent_audit_log table — an append-only log stored in your local Atlas database. The audit log captures: timestamp, tool name, full arguments, result count, and query duration. This is your record of what agents asked and when.

The audit table uses clear, human-readable column names and lives in the same SQLite file as the rest of your Atlas data. You can query it directly with any SQLite tool, back it up with a file copy, or delete it entirely — it’s your data.

Viewing the Audit Log

atlas audit                        # Recent queries (default: 50)
atlas audit --today                # Today's queries only
atlas audit --tool atlas_search    # Filter by tool name
atlas audit --agent <id>           # Filter by agent ID
atlas audit -n 100                 # Show more entries
atlas audit --json                 # Machine-readable output

Activity Summary

atlas audit summary               # Last 7 days, grouped by tool
atlas audit summary --days 30     # Last 30 days
atlas audit summary --json

The summary shows a bar chart of query volume per tool:

Agent activity (last 7 days):

  atlas_search         ████████████████████ 42 queries
  atlas_history        ████████████         24 queries
  atlas_trace          ██████               12 queries
  atlas_status         ███                  6 queries

  84 total queries

CLI Agent Path

For agents that don’t support MCP, every Atlas command supports --json for structured output. The agent calls Atlas as a subprocess and parses the JSON response. This path adds no dependencies — it’s the same CLI you already use, with a flag for machine-readable output.

Commands available to agents:

atlas status --json              # What Atlas is tracking
atlas history <path> --json      # Full file history
atlas find --duplicates --json   # Find duplicate files
atlas search <query> --json      # Search by name/path/hash
atlas trace <path> --json        # Lineage (--forward or --backward)
atlas inputs <path> --json       # What does this file need?
atlas outputs <path> --json      # What does this file produce?
atlas impact <path> --json       # What breaks if this changes?
atlas broken --json              # Unresolved references
atlas compare <a> <b> --json     # Content-identity comparison
atlas log --today --json         # Recent activity
atlas tree <path> --json         # Fork visualization

Opt-in CLI Audit Logging

By default, CLI --json calls are not logged. This is intentional — the CLI is your direct interface, and logging your own usage is a choice, not a default. To enable audit logging for CLI calls, add to ~/.atlas/config.toml:

audit_cli = true

When enabled, any --json command execution is logged to the same agent_audit_log table as MCP queries, with source = "cli". This lets you see a unified view of all programmatic access to your Atlas data, whether from an agent or a script you wrote.

Note: Connect Scope filtering applies only to MCP queries. CLI --json calls are the user’s own interface and always return unfiltered results, regardless of scope configuration.

Building Without MCP

The MCP server requires the mcp feature flag (enabled by default). To build without it:

cargo build --no-default-features

This removes the rmcp, tokio, schemars, and axum dependencies entirely. The atlas connect commands will print an error message if invoked. The CLI agent path (--json) works regardless of feature flags — it has no additional dependencies.

Building without MCP gives you a smaller binary with a reduced dependency surface. Atlas is a complete product without Connect; Connect is an optional layer you choose to enable.